Merge remote-tracking branch 'origin/main' into suppress-inject

packages/opentelemetry-core/src/context/propagation/HttpTraceContext.ts

@@ -18,6 +18,7 @@ import {
   Context,
   getSpanContext,
   isInstrumentationSuppressed,
+  isSpanContextValid,
   setSpanContext,
   SpanContext,
   TextMapGetter,
@@ -74,7 +75,12 @@ export function parseTraceParent(traceParent: string): SpanContext | null {
 export class HttpTraceContext implements TextMapPropagator {
   inject(context: Context, carrier: unknown, setter: TextMapSetter) {
     const spanContext = getSpanContext(context);
-    if (!spanContext || isInstrumentationSuppressed(context)) return;
+    if (
+      !spanContext ||
+      isInstrumentationSuppressed(context) ||
+      !isSpanContextValid(spanContext)
+    )
+      return;
 
     const traceParent = `${VERSION}-${spanContext.traceId}-${
       spanContext.spanId

packages/opentelemetry-core/test/context/HttpTraceContext.test.ts

@@ -17,13 +17,15 @@
 import {
   defaultTextMapGetter,
   defaultTextMapSetter,
-  SpanContext,
-  TraceFlags,
   getSpanContext,
+  INVALID_SPANID,
+  INVALID_TRACEID,
+  ROOT_CONTEXT,
   setSpanContext,
+  SpanContext,
   suppressInstrumentation,
+  TraceFlags,
 } from '@opentelemetry/api';
-import { ROOT_CONTEXT } from '@opentelemetry/api';
 import * as assert from 'assert';
 import {
   HttpTraceContext,
@@ -85,6 +87,22 @@ describe('HttpTraceContext', () => {
         traceId: 'd4cda95b652f4a1592b449d5929fda1b',
         spanId: '6e0c63257de34c92',
         traceFlags: TraceFlags.SAMPLED,
+      };
+
+      httpTraceContext.inject(
+        suppressInstrumentation(setSpanContext(ROOT_CONTEXT, spanContext)),
+        carrier,
+        defaultTextMapSetter
+      );
+      assert.strictEqual(carrier[TRACE_PARENT_HEADER], undefined);
+      assert.strictEqual(carrier[TRACE_STATE_HEADER], undefined);
+    });
+
+    it('should ignore invalid span context', () => {
+      const spanContext: SpanContext = {
+        traceId: INVALID_TRACEID,
+        spanId: INVALID_SPANID,
+        traceFlags: TraceFlags.NONE,
         traceState: new TraceState('foo=bar,baz=qux'),
       };
 

packages/opentelemetry-tracing/src/Span.ts

@@ -193,7 +193,7 @@ export class Span implements api.Span, ReadableSpan {
       attributes[ExceptionAttribute.MESSAGE] = exception;
     } else if (exception) {
       if (exception.code) {
-        attributes[ExceptionAttribute.TYPE] = exception.code;
+        attributes[ExceptionAttribute.TYPE] = exception.code.toString();
       } else if (exception.name) {
         attributes[ExceptionAttribute.TYPE] = exception.name;
       }

packages/opentelemetry-tracing/test/Span.test.ts

@@ -719,5 +719,23 @@ describe('Span', () => {
         assert.deepStrictEqual(event.time, [0, 123]);
       });
     });
+
+    describe('when exception code is numeric', () => {
+      it('should record an exception with string value', () => {
+        const span = new Span(
+          tracer,
+          ROOT_CONTEXT,
+          name,
+          spanContext,
+          SpanKind.CLIENT
+        );
+        assert.strictEqual(span.events.length, 0);
+        span.recordException({ code: 12 });
+        const event = span.events[0];
+        assert.deepStrictEqual(event.attributes, {
+          [ExceptionAttribute.TYPE]: '12',
+        });
+      });
+    });
   });
 });

website_docs/_index.md

@@ -0,0 +1,26 @@
+---
+title: "Javascript"
+weight: 20
+description: >
+  <img width="35" src="https://raw.github.com/open-telemetry/opentelemetry.io/main/iconography/32x32/JS_SDK.svg"></img>
+  A language-specific implementation of OpenTelemetry in JavaScript (for Node.JS & the browser).
+---
+
+This page contains an introduction to OpenTelemetry in JavaScript. This guide
+will walk you through installation and instrumentation and show you how to
+export data.
+
+## Status and Releases
+
+| Tracing | Metrics |
+| ------- | ------- |
+| Beta    | Alpha   |
+
+You can find release information [here](https://github.com/open-telemetry/opentelemetry-js/releases)
+
+## Further Reading
+
+- [OpenTelemetry for JavaScript on GitHub](https://github.com/open-telemetry/opentelemetry-js)
+- [Getting Started](https://github.com/open-telemetry/opentelemetry-js/blob/main/getting-started/README.md)
+- [API Documentation](https://open-telemetry.github.io/opentelemetry-js)
+- [Getting In Touch (Gitter)](https://gitter.im/open-telemetry/opentelemetry-node)

website_docs/getting_started/_index.md

@@ -0,0 +1,9 @@
+---
+title: "Getting Started"
+weight: 1
+---
+These two guides for Node.JS and the browser use simple examples in javascript to get you started with OpenTelemetry. Both will show you the following steps:
+
+- Install the required OpenTelemetry libraries
+- Initialize a global [tracer](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#tracer)
+- Initialize and register a [span exporter](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#span-exporter)

website_docs/getting_started/browser.md

@@ -0,0 +1,188 @@
+---
+title: "Browser"
+weight: 2
+---
+
+This guide uses the example application in HTML & javascript provided below, but the steps to instrument your own application should be broadly the same. Here is an overview of what we will be doing.
+
+- Install the required OpenTelemetry libraries
+- Initialize a global [tracer](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#tracer)
+- Initialize and register a [span exporter](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#span-exporter)
+
+This is a very simple guide, if you'd like to see more complex examples go to [examples/tracer-web](https://github.com/open-telemetry/opentelemetry-js/tree/main/examples/tracer-web)
+
+Copy the following file into an empty directory and call it `index.html`.
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Document Load Plugin Example</title>
+  <base href="/">
+  <!--
+    https://www.w3.org/TR/trace-context/
+    Set the `traceparent` in the server's HTML template code. It should be
+    dynamically generated server side to have the server's request trace Id,
+    a parent span Id that was set on the server's request span, and the trace
+    flags to indicate the server's sampling decision
+    (01 = sampled, 00 = notsampled).
+    '{version}-{traceId}-{spanId}-{sampleDecision}'
+  -->
+  <meta name="traceparent" content="00-ab42124a3c573678d4d8b21ba52df3bf-d21f7bc17caa5aba-01">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+</head>
+<body>
+  Example of using Web Tracer with document load plugin with console exporter and collector exporter
+</body>
+</html>
+```
+
+## Installation
+
+To create traces in the browser, you will need `@opentelemetry/web`, and the plugin `@opentelemetry/plugin-document-load`:
+
+```shell
+npm install @opentelemetry/web @opentelemetry/plugin-document-load
+```
+
+In the following we will use parcel as web application bundler, but you can of course also use any other build tool:
+
+```shell
+npm install -g parcel
+```
+
+## Initialization and Configuration
+
+Create a empty file called `document-load.js` and add the following code to your html right before the body end tag:
+
+```html
+<script type="text/javascript" src="document-load.js"></script>
+```
+
+We will add some code that will trace the document load timings and output those as OpenTelemetry Spans.
+
+## Creating a Tracer Provider
+
+Add the following code to the `document-load.js` to create a tracer provider, which brings the plugin to trace document load:
+
+```javascript
+ // This is necessary for "parcel" to work OOTB. It is not needed for other build tools.
+import 'regenerator-runtime/runtime'
+import { LogLevel } from "@opentelemetry/core";
+import { WebTracerProvider } from '@opentelemetry/web';
+import { DocumentLoad } from '@opentelemetry/plugin-document-load';
+
+// Minimum required setup - supports only synchronous operations
+const provider = new WebTracerProvider({
+  plugins: [
+    new DocumentLoad()
+  ]
+});
+provider.register();
+```
+
+Run `parcel index.html` and open the development webserver (e.g. at `http://localhost:1234`) to see if your code works.
+
+There will be no output of traces yet, for this we need to add an exporter
+
+## Creating a Console Exporter
+
+To export traces, modify `document-load.js` so that it matches the following code snippet:
+
+```javascript
+ // This is necessary for "parcel" to work OOTB. It is not needed for other build tools.
+import 'regenerator-runtime/runtime'
+import { LogLevel } from "@opentelemetry/core";
+import { WebTracerProvider } from '@opentelemetry/web';
+import { DocumentLoad } from '@opentelemetry/plugin-document-load';
+import { ConsoleSpanExporter, SimpleSpanProcessor } from '@opentelemetry/tracing';
+
+// Minimum required setup - supports only synchronous operations
+const provider = new WebTracerProvider({
+  plugins: [
+    new DocumentLoad()
+  ]
+});
+provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()))
+provider.register();
+```
+
+Now, rebuild your application and open the browser again. In the console of the developer toolbar you should see some traces being exporterd:
+
+```json
+{
+  "traceId": "ab42124a3c573678d4d8b21ba52df3bf",
+  "parentId": "cfb565047957cb0d",
+  "name": "documentFetch",
+  "id": "5123fc802ffb5255",
+  "kind": 0,
+  "timestamp": 1606814247811266,
+  "duration": 9390,
+  "attributes": {
+    "component": "document-load",
+    "http.response_content_length": 905
+  },
+  "status": {
+    "code": 0
+  },
+  "events": [
+    {
+      "name": "fetchStart",
+      "time": [
+        1606814247,
+        811266158
+      ]
+    },
+    {
+      "name": "domainLookupStart",
+      "time": [
+        1606814247,
+        811266158
+      ]
+    },
+    {
+      "name": "domainLookupEnd",
+      "time": [
+        1606814247,
+        811266158
+      ]
+    },
+    {
+      "name": "connectStart",
+      "time": [
+        1606814247,
+        811266158
+      ]
+    },
+    {
+      "name": "connectEnd",
+      "time": [
+        1606814247,
+        811266158
+      ]
+    },
+    {
+      "name": "requestStart",
+      "time": [
+        1606814247,
+        819101158
+      ]
+    },
+    {
+      "name": "responseStart",
+      "time": [
+        1606814247,
+        819791158
+      ]
+    },
+    {
+      "name": "responseEnd",
+      "time": [
+        1606814247,
+        820656158
+      ]
+    }
+  ]
+}
+```