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.

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

docs: fix examples in website_docs/instrumentation.md #2412

Merged
merged 3 commits into from Aug 14, 2021
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
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
46 changes: 15 additions & 31 deletions website_docs/getting_started/nodejs.md
Expand Up @@ -72,9 +72,9 @@ The following dependencies are required to trace a Node.js application.

These dependencies are required to configure the tracing SDK and create spans.

- `@opentelemetry/api`
- `@opentelemetry/sdk-trace-node`
- `@opentelemetry/sdk-trace-base`
```shell
npm install @opentelemetry/sdk-node @opentelemetry/api
```

#### Exporter

Expand All @@ -91,6 +91,10 @@ Many common modules such as the `http` standard library module, `express`, and o

You can also install all instrumentations maintained by the OpenTelemetry authors by using the `@opentelemetry/auto-instrumentations-node` module.

```shell
npm install @opentelemetry/auto-instrumentations-node
```

### Setup

The tracing setup and configuration should be run before your application code. One tool commonly used for this task is the [`-r, --require module`](https://nodejs.org/api/cli.html#cli_r_require_module) flag.
Expand All @@ -101,47 +105,27 @@ Create a file with a name like `tracing.js` which will contain your tracing setu
/* tracing.js */

// Require dependencies
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { SimpleSpanProcessor, ConsoleSpanExporter } = require("@opentelemetry/sdk-trace-base");
const { getNodeAutoInstrumentations } = require("@opentelemetry/auto-instrumentations-node');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');

// Create a tracer provider
const provider = new NodeTracerProvider();

// The exporter handles sending spans to your tracing backend
const exporter = new ConsoleSpanExporter();

// The simple span processor sends spans to the exporter as soon as they are ended.
const processor = new SimpleSpanProcessor(exporter);
provider.addSpanProcessor(processor);
const opentelemetry = require("@opentelemetry/sdk-node");
const { getNodeAutoInstrumentations } = require("@opentelemetry/auto-instrumentations-node");

// The provider must be registered in order to
// be used by the OpenTelemetry API and instrumentations
provider.register();

// This will automatically enable all instrumentations
registerInstrumentations({
instrumentations: [getNodeAutoInstrumentations()],
const sdk = new opentelemetry.NodeSDK({
traceExporter: new opentelemetry.tracing.ConsoleSpanExporter(),
instrumentations: [getNodeAutoInstrumentations()]
});

sdk.start()
```

### Run Application

First, install the dependencies as described above. Here you need to add the following:

```shell
npm install --save @opentelemetry/sdk-trace-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.

```shell
$ node --require './tracing.js' app.js
Listening for requests on http://localhost:8080
```

Now, when you open <http://localhost:8080> in your web browser, you should see the spans printed in the console by the `ConsoleSpanExporter`.
Open <http://localhost:8080> in your web browser and reload the page a few times, after a while you should see the spans printed in the console by the `ConsoleSpanExporter`.

<details>
<summary>View example output</summary>
Expand Down
23 changes: 11 additions & 12 deletions website_docs/instrumentation.md
Expand Up @@ -108,16 +108,17 @@ for (let i = 0; i < 10; i += 1) {
function doWork(parent) {
// Start another span. In this example, the main method already started a
// span, so that'll be the parent span, and this will be a child span.
const span = tracer.startSpan('doWork', {
parent,
});
const ctx = opentelemetry.trace.setSpan(opentelemetry.context.active(), parent);
const span = tracer.startSpan('doWork', undefined, ctx);

// simulate some random work.
for (let i = 0; i <= Math.floor(Math.random() * 40000000); i += 1) {
// empty
}
span.end();
}
// Be sure to end the span.
parentSpan.end();
```

Invoking your application once again will give you a list of traces being exported.
Expand All @@ -128,9 +129,8 @@ Attributes can be used to describe your spans. Attributes can be added to a span

```javascript
function doWork(parent) {
const span = tracer.startSpan('doWork', {
parent, attributes: { attribute1 : 'value1' }
});
const ctx = opentelemetry.trace.setSpan(opentelemetry.context.active(), parent);
const span = tracer.startSpan('doWork', { attributes: { attribute1 : 'value1' } }, ctx);
for (let i = 0; i <= Math.floor(Math.random() * 40000000); i += 1) {
// empty
}
Expand Down Expand Up @@ -159,9 +159,8 @@ Finally, you can update your file to include semantic attributes:

```javascript
function doWork(parent) {
const span = tracer.startSpan('doWork', {
parent, attributes: { SemanticAttributes.CODE_FUNCTION : 'doWork' }
});
const ctx = opentelemetry.trace.setSpan(opentelemetry.context.active(), parent);
const span = tracer.startSpan('doWork', { attributes: { [SemanticAttributes.CODE_FUNCTION] : 'doWork' } }, ctx);
for (let i = 0; i <= Math.floor(Math.random() * 40000000); i += 1) {
// empty
}
Expand All @@ -178,9 +177,9 @@ The status can be set at any time before the span is finished:

```javascript
function doWork(parent) {
const span = tracer.startSpan('doWork', {
parent,
});
const ctx = opentelemetry.trace.setSpan(opentelemetry.context.active(), parent);
const span = tracer.startSpan('doWork', undefined, ctx);

span.setStatus({
code: opentelemetry.SpanStatusCode.OK,
message: 'Ok.'
Expand Down