Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

fix: update and make website docs work #2324

Merged
merged 8 commits into from Jul 11, 2021
Merged

fix: update and make website docs work #2324

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
1cc776d
fix: update and make website docs work
svrnm Jul 6, 2021
4d21cb8
Merge branch 'open-telemetry:main' into website-docs-review
svrnm Jul 6, 2021
c9c2242
fix: remove lint errors from docs update
svrnm Jul 6, 2021
4ebfb7e
Merge branch 'main' of github.com:open-telemetry/opentelemetry-js int…
svrnm Jul 6, 2021
041b951
Merge branch 'website-docs-review' of github.com:svrnm/opentelemetry-…
svrnm Jul 6, 2021
6ffce4e
Update website_docs/getting_started/browser.md
svrnm Jul 6, 2021
9ee9952
Merge branch 'main' into website-docs-review
svrnm Jul 6, 2021
7947179
Merge branch 'main' into website-docs-review
vmarchaud Jul 11, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
31 changes: 15 additions & 16 deletions website_docs/getting_started/browser.md
View file
Open in desktop
Expand Up @@ -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
Expand All @@ -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';

Expand All @@ -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

Expand All @@ -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';

Expand All @@ -117,7 +116,7 @@ provider.register({
// Registering instrumentations / plugins
registerInstrumentations({
instrumentations: [
new DocumentLoad(),
new DocumentLoadInstrumentation(),
],
});
```
Expand Down
138 changes: 72 additions & 66 deletions website_docs/getting_started/nodejs.md
View file
Open in desktop
Expand Up @@ -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
Expand All @@ -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
```
Expand All @@ -138,80 +144,80 @@ Now, when you open <http://localhost:8080> 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": []
}
```

Expand Down
43 changes: 27 additions & 16 deletions website_docs/instrumentation.md
View file
Open in desktop
Expand Up @@ -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": []
}
```

Expand Down Expand Up @@ -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();
}
```