From 5cfa88d047ad6866b52a7c44afc52be66a095a05 Mon Sep 17 00:00:00 2001 From: Severin Neumann Date: Sun, 11 Jul 2021 10:12:45 +0200 Subject: [PATCH] fix: update and make website docs work (#2324) Co-authored-by: Jonathan Church Co-authored-by: Valentin Marchaud --- website_docs/getting_started/browser.md | 31 +++--- website_docs/getting_started/nodejs.md | 138 ++++++++++++------------ website_docs/instrumentation.md | 43 +++++--- 3 files changed, 114 insertions(+), 98 deletions(-) diff --git a/website_docs/getting_started/browser.md b/website_docs/getting_started/browser.md index 42a451e526..691604124f 100644 --- a/website_docs/getting_started/browser.md +++ b/website_docs/getting_started/browser.md @@ -43,13 +43,8 @@ Copy the following file into an empty directory and call it `index.html`. 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 +npm init -y +npm install --save @opentelemetry/web @opentelemetry/instrumentation-document-load @opentelemetry/context-zone ``` ## Initialization and Configuration @@ -67,10 +62,8 @@ We will add some code that will trace the document load timings and output those 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 { WebTracerProvider } from '@opentelemetry/web'; -import { DocumentLoad } from '@opentelemetry/plugin-document-load'; +import { DocumentLoadInstrumentation } from '@opentelemetry/instrumentation-document-load'; import { ZoneContextManager } from '@opentelemetry/context-zone'; import { registerInstrumentations } from '@opentelemetry/instrumentation'; @@ -84,12 +77,20 @@ provider.register({ // Registering instrumentations / plugins registerInstrumentations({ instrumentations: [ - new DocumentLoad(), + new DocumentLoadInstrumentation(), ], }); ``` -Run `parcel index.html` and open the development webserver (e.g. at `http://localhost:1234`) to see if your code works. +In the following we will use [parcel](https://parceljs.org/) as web application bundler, but you can of course also use any other build tool. + +Run + +```shell +npx 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 @@ -98,11 +99,9 @@ There will be no output of traces yet, for this we need to add an 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 { ConsoleSpanExporter, SimpleSpanProcessor } from '@opentelemetry/tracing'; import { WebTracerProvider } from '@opentelemetry/web'; -import { DocumentLoad } from '@opentelemetry/plugin-document-load'; +import { DocumentLoadInstrumentation } from '@opentelemetry/instrumentation-document-load'; import { ZoneContextManager } from '@opentelemetry/context-zone'; import { registerInstrumentations } from '@opentelemetry/instrumentation'; @@ -117,7 +116,7 @@ provider.register({ // Registering instrumentations / plugins registerInstrumentations({ instrumentations: [ - new DocumentLoad(), + new DocumentLoadInstrumentation(), ], }); ``` diff --git a/website_docs/getting_started/nodejs.md b/website_docs/getting_started/nodejs.md index 0cc5278071..73cbf1f2af 100644 --- a/website_docs/getting_started/nodejs.md +++ b/website_docs/getting_started/nodejs.md @@ -99,7 +99,7 @@ Create a file with a name like `tracing.js` which will contain your tracing setu // Require dependencies const { NodeTracerProvider } = require("@opentelemetry/node"); const { SimpleSpanProcessor, ConsoleSpanExporter } = require("@opentelemetry/tracing"); -const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node'); +const { getNodeAutoInstrumentations } = require("@opentelemetry/auto-instrumentations-node'); const { registerInstrumentations } = require('@opentelemetry/instrumentation'); // Create a tracer provider @@ -124,9 +124,15 @@ registerInstrumentations({ ### Run Application +First, install the dependencies as described above. Here you need to add the following: + +```shell +npm install --save @opentelemetry/node @opentelemetry/auto-instrumentations-node +``` + Now you can run your application as you normally would, but you can use the `--require` flag to load the tracing code before the application code. -```sh +```shell $ node --require './tracing.js' app.js Listening for requests on http://localhost:8080 ``` @@ -138,80 +144,80 @@ Now, when you open in your web browser, you should see t ```json { - traceId: '3f1fe6256ea46d19ec3ca97b3409ad6d', - parentId: 'f0b7b340dd6e08a7', - name: 'middleware - query', - id: '41a27f331c7bfed3', - kind: 0, - timestamp: 1624982589722992, - duration: 417, - attributes: { - 'http.route': '/', - 'express.name': 'query', - 'express.type': 'middleware' + "traceId": "3f1fe6256ea46d19ec3ca97b3409ad6d", + "parentId": "f0b7b340dd6e08a7", + "name": "middleware - query", + "id": "41a27f331c7bfed3", + "kind": 0, + "timestamp": 1624982589722992, + "duration": 417, + "attributes": { + "http.route": "/", + "express.name": "query", + "express.type": "middleware" }, - status: { code: 0 }, - events: [] + "status": { "code": 0 }, + "events": [] } { - traceId: '3f1fe6256ea46d19ec3ca97b3409ad6d', - parentId: 'f0b7b340dd6e08a7', - name: 'middleware - expressInit', - id: 'e0ed537a699f652a', - kind: 0, - timestamp: 1624982589725778, - duration: 673, - attributes: { - 'http.route': '/', - 'express.name': 'expressInit', - 'express.type': 'middleware' + "traceId": "3f1fe6256ea46d19ec3ca97b3409ad6d", + "parentId": "f0b7b340dd6e08a7", + "name": "middleware - expressInit", + "id": "e0ed537a699f652a", + "kind": 0, + "timestamp": 1624982589725778, + "duration": 673, + "attributes": { + "http.route": "/", + "express.name": "expressInit", + "express.type": "middleware" }, - status: { code: 0 }, - events: [] + "status": { code: 0 }, + "events": [] } { - traceId: '3f1fe6256ea46d19ec3ca97b3409ad6d', - parentId: 'f0b7b340dd6e08a7', - name: 'request handler - /', - id: '8614a81e1847b7ef', - kind: 0, - timestamp: 1624982589726941, - duration: 21, - attributes: { - 'http.route': '/', - 'express.name': '/', - 'express.type': 'request_handler' + "traceId": "3f1fe6256ea46d19ec3ca97b3409ad6d", + "parentId": "f0b7b340dd6e08a7", + "name": "request handler - /", + "id": "8614a81e1847b7ef", + "kind": 0, + "timestamp": 1624982589726941, + "duration": 21, + "attributes": { + "http.route": "/", + "express.name": "/", + "express.type": "request_handler" }, - status: { code: 0 }, - events: [] + "status": { code: 0 }, + "events": [] } { - traceId: '3f1fe6256ea46d19ec3ca97b3409ad6d', - parentId: undefined, - name: 'GET /', - id: 'f0b7b340dd6e08a7', - kind: 1, - timestamp: 1624982589720260, - duration: 11380, - attributes: { - 'http.url': 'http://localhost:8080/', - 'http.host': 'localhost:8080', - 'net.host.name': 'localhost', - 'http.method': 'GET', - 'http.route': '', - 'http.target': '/', - 'http.user_agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.114 Safari/537.36', - 'http.flavor': '1.1', - 'net.transport': 'ip_tcp', - 'net.host.ip': '::1', - 'net.host.port': 8080, - 'net.peer.ip': '::1', - 'net.peer.port': 61520, - 'http.status_code': 304, - 'http.status_text': 'NOT MODIFIED' + "traceId": "3f1fe6256ea46d19ec3ca97b3409ad6d", + "parentId": undefined, + "name": "GET /", + "id": "f0b7b340dd6e08a7", + "kind": 1, + "timestamp": 1624982589720260, + "duration": 11380, + "attributes": { + "http.url": "http://localhost:8080/", + "http.host": "localhost:8080", + "net.host.name": "localhost", + "http.method": "GET", + "http.route": "", + "http.target": "/", + "http.user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.114 Safari/537.36", + "http.flavor": "1.1", + "net.transport": "ip_tcp", + "net.host.ip": "::1", + "net.host.port": 8080, + "net.peer.ip": "::1", + "net.peer.port": 61520, + "http.status_code": 304, + "http.status_text": "NOT MODIFIED" }, - status: { code: 1 }, - events: [] + "status": { "code": 1 }, + "events": [] } ``` diff --git a/website_docs/instrumentation.md b/website_docs/instrumentation.md index 91d21bd6cc..93a7f76924 100644 --- a/website_docs/instrumentation.md +++ b/website_docs/instrumentation.md @@ -67,25 +67,22 @@ for (let i = 0; i < 10; i += 1) { } // Be sure to end the span. parentSpan.end(); - -// flush and close the connection. -exporter.shutdown(); ``` Run your application and you will see traces being exported to the console: ```json { - traceId: '833bac85797c7ace581235446c4c769a', - parentId: undefined, - name: 'main', - id: '5c82d9e39d58229e', - kind: 0, - timestamp: 1603790966012813, - duration: 13295, - attributes: {}, - status: { code: 0 }, - events: [] + "traceId": "833bac85797c7ace581235446c4c769a", + "parentId": undefined, + "name": "main", + "id": "5c82d9e39d58229e", + "kind": 0, + "timestamp": 1603790966012813, + "duration": 13295, + "attributes": {}, + "status": { "code": 0 }, + "events": [] } ``` @@ -136,17 +133,31 @@ function doWork(parent) { ### Semantic Attributes -There are semantic conventions for spans representing operations in well-known protocols like HTTP or database calls. Semantic conventions for these spans are defined in the specification at [Trace Semantic Conventions](https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/trace/semantic_conventions). In the simple example of this guide the source code attributes can be used: +There are semantic conventions for spans representing operations in well-known protocols like HTTP or database calls. Semantic conventions for these spans are defined in the specification at [Trace Semantic Conventions](https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/trace/semantic_conventions). In the simple example of this guide the source code attributes can be used. + +First add the semantic conventions as a dependency to your application: + +```shell +npm install --save @opentelemetry/semantic-conventions +``` + +Add the following to the top of your application file: + +```javascript +const { SemanticAttributes } = require('@opentelemetry/semantic-conventions'); +``` + +Finally, you can update your file to include semantic attributes: ```javascript function doWork(parent) { const span = tracer.startSpan('doWork', { - parent, attributes: { 'code.function' : 'doWork' } + parent, attributes: { SemanticAttributes.CODE_FUNCTION : 'doWork' } }); for (let i = 0; i <= Math.floor(Math.random() * 40000000); i += 1) { // empty } - span.setAttribute('code.filepath', __filename); + span.setAttribute(SemanticAttributes.CODE_FILEPATH, __filename); span.end(); } ```