From 6c9e19cb9d2719da021b758357e108ad6131a52b Mon Sep 17 00:00:00 2001 From: svrnm Date: Thu, 5 Aug 2021 11:14:32 +0200 Subject: [PATCH 1/8] fix: update status and releases for docs. --- website_docs/_index.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/website_docs/_index.md b/website_docs/_index.md index 1f8bed9e7d..1c1d246ff2 100644 --- a/website_docs/_index.md +++ b/website_docs/_index.md @@ -12,10 +12,11 @@ export data. ## Status and Releases -| | Tracing | Metrics | -| ----- | ------- | ------- | -| API | GA | Alpha | -| SDK | Beta | Alpha | +| Signal | API Status | SDK Status | +|---------|-------------|-------------------| +| Tracing | Stable | Release Candidate | +| Metrics | Development | Development | +| Logs | Roadmap | Roadmap | You can find release information [here](https://github.com/open-telemetry/opentelemetry-js/releases) From 9b96e3fa5a6c152b15faaa092d3075172f6caee4 Mon Sep 17 00:00:00 2001 From: svrnm Date: Thu, 5 Aug 2021 11:16:50 +0200 Subject: [PATCH 2/8] docs: update further reading in docs index. --- website_docs/_index.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/website_docs/_index.md b/website_docs/_index.md index 1c1d246ff2..99262d9b7a 100644 --- a/website_docs/_index.md +++ b/website_docs/_index.md @@ -23,6 +23,5 @@ You can find release information [here](https://github.com/open-telemetry/opente ## 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) +- [API Reference](https://open-telemetry.github.io/opentelemetry-js-api) +- [SDK Reference](https://open-telemetry.github.io/opentelemetry-js) From dc516ce1fc2f347962ee7ddc11cce3e6e938dd0a Mon Sep 17 00:00:00 2001 From: svrnm Date: Thu, 5 Aug 2021 11:55:42 +0200 Subject: [PATCH 3/8] docs: add metrics to website docs. --- website_docs/exporters.md | 45 ++++++++- website_docs/getting_started/nodejs.md | 125 ++++++++++++++++++++++++- website_docs/instrumentation.md | 7 ++ 3 files changed, 174 insertions(+), 3 deletions(-) diff --git a/website_docs/exporters.md b/website_docs/exporters.md index c1ce99369a..562b914e47 100644 --- a/website_docs/exporters.md +++ b/website_docs/exporters.md @@ -3,11 +3,15 @@ title: "Exporters" weight: 3 --- -In order to visualize and analyze your traces, you will need to export them to a tracing backend such as Jaeger or Zipkin. -OpenTelemetry JS provides exporters for some common open source tracing backends. +In order to visualize and analyze your traces and metrics, you will need to export them to a backend such as [Jaeger](https://www.jaegertracing.io/) or [Zipkin](https://zipkin.io/). OpenTelemetry JS provides exporters for some common open source backends. Below you will find some introductions on how to setup backends and the matching exporters. +- [Jaeger](#jaeger) +- [Zipkin](#zipkin) +- [Prometheus](#prometheus) +- [OpenTelemetry Collector](#opentelemetry-collector) + ## Jaeger To set up Jaeger as quickly as possible, run it in a docker container: @@ -64,6 +68,43 @@ const { BatchSpanProcessor } = require("@opentelemetry/tracing"); provider.addSpanProcessor(new BatchSpanProcessor(new ZipkinExporter())) ``` +## Prometheus + +To set up Prometheus as quickly as possible, run it in a docker container. +You will need a `prometheus.yml` to configure the backend, use the following example +and modify it to your needs: + +```yml +global: + scrape_interval: 15s + evaluation_interval: 15s + +scrape_configs: + - job_name: "prometheus" + static_configs: + - targets: ["localhost:9090"] +``` + +With this file you can now start the docker container: + +```shell +docker run \ + -p 9090:9090 \ + -v ${PWD}/prometheus.yml:/etc/prometheus/prometheus.yml \ + prom/prometheus +``` + +Update your opentelemetry configuration to use the exporter and to send data to your prometheus backend: + +```javascript +const { PrometheusExporter } = require('@opentelemetry/exporter-prometheus'); +const { MeterProvider } = require('@opentelemetry/metrics'); +const meter = new MeterProvider({ + exporter: new PrometheusExporter({port: 9090}), + interval: 1000, +}).getMeter('prometheus'); +``` + ## OpenTelemetry Collector If you are looking for a vendor-agnostic way to receive, process and export your diff --git a/website_docs/getting_started/nodejs.md b/website_docs/getting_started/nodejs.md index 92ef2c1be9..5dc83ef99f 100644 --- a/website_docs/getting_started/nodejs.md +++ b/website_docs/getting_started/nodejs.md @@ -15,6 +15,12 @@ This guide will show you how to get started with tracing in Node.js. - [Instrumentation Modules](#instrumentation-modules) - [Setup](#setup) - [Run Application](#run-application) +- [Metrics](#metrics) + - [Dependencies](#dependencies-2) + - [Core Dependencies](#core-dependencies-1) + - [Exporter](#exporter-1) + - [Setup](#setup-1) + - [Run Application](#run-application-1) ## Example Application @@ -97,7 +103,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 @@ -220,3 +226,120 @@ Now, when you open in your web browser, you should see t ``` + +## Metrics + +### Dependencies + +The following dependencies are required to collect metrics in your Node.js application. + +#### Core Dependencies + +These dependencies are required to configure the tracing SDK and create spans. + +- `@opentelemetry/metrics` + +#### Exporter + +In the following example, we will use the `ConsoleMetricExporter` which prints all spans to the console. + +In order to visualize and analyze your metrics, you will need to export them to a metrics backend. +Follow [these instructions](../exporters.md) for setting up a backend and exporter. + +### Setup + +You need a `Meter` to create and monitor metrics. A `Meter` in OpenTelemetry is the mechanism used to create and manage metrics, labels, and metric exporters. + +Create a file named `monitoring.js` and add the following code: + +```javascript +/* monitoring.js */ +'use strict'; + +const { MeterProvider, ConsoleMetricExporter } = require('@opentelemetry/metrics'); + +const meter = new MeterProvider({ + new ConsoleMetricExporter(), + interval: 1000, +}).getMeter('your-meter-name'); +``` + +Now you can require this file from your application code and use the `Meter` to create and manage metrics. The simplest of these metrics is a counter. + +Let's create and export from your `monitoring.js` file a middleware function that express can use to count all requests by route. Modify the `monitoring.js` file so it looks like this: + +```javascript +/* monitoring.js */ +'use strict'; + +const { MeterProvider, ConsoleMetricExporter } = require('@opentelemetry/metrics'); + +const meter = new MeterProvider({ + new ConsoleMetricExporter(), + interval: 1000, +}).getMeter('your-meter-name'); + +const requestCount = meter.createCounter("requests", { + description: "Count all incoming requests" +}); + +const boundInstruments = new Map(); + +module.exports.countAllRequests = () => { + return (req, res, next) => { + if (!boundInstruments.has(req.path)) { + const labels = { route: req.path }; + const boundCounter = requestCount.bind(labels); + boundInstruments.set(req.path, boundCounter); + } + + boundInstruments.get(req.path).add(1); + next(); + }; +}; +``` + +Now import and use this middleware in your application code `app.js`: + +```javascript +/* app.js */ +const express = require("express"); +const { countAllRequests } = require("./monitoring"); +const app = express(); +app.use(countAllRequests()); +/* ... */ +``` + +Now when you make requests to your service, your meter will count all requests. + +**Note**: Creating a new labelSet and binding on every request is not ideal because creating the labelSet can often be an expensive operation. Therefore, the instruments are created and stored in a Map according to the route key. + +### Run Application + +First, install the dependencies as described above. Here you need to add the following: + +```shell +npm install --save @opentelemetry/metrics +``` + +Now you can run your application: + +```shell +$ node app.js +Listening for requests on http://localhost:8080 +``` + +Now, when you open in your web browser, you should see the metrics printed in the console by the `ConsoleMetricExporter`. + + +```json +{ + "name": "requests", + "description": "Count all incoming requests", + "unit": '1', + "metricKind": 0, + "valueType": 1 +} +{ "route": "/" } +"value": "1" +``` \ No newline at end of file diff --git a/website_docs/instrumentation.md b/website_docs/instrumentation.md index 93a7f76924..fe5bf3466e 100644 --- a/website_docs/instrumentation.md +++ b/website_docs/instrumentation.md @@ -5,6 +5,13 @@ weight: 3 This guide will cover creating and annotating spans, creating and annotating metrics, how to pass context, and a guide to automatic instrumentation for JavaScript. This simple example works in the browser as well as with Node.JS +- [Example Application](#example-application) +- [Creating Spans](#creating-spans) +- [Attributes](#attributes) + - [Semantic Attributes](#semantic-attributes) + +## Example Application + In the following this guide will use the following sample app: ```javascript From 412061d1e9cae7732f699e1a572e7a36b87a0a10 Mon Sep 17 00:00:00 2001 From: svrnm Date: Thu, 5 Aug 2021 12:14:08 +0200 Subject: [PATCH 4/8] docs: add span status to website docs --- website_docs/instrumentation.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/website_docs/instrumentation.md b/website_docs/instrumentation.md index fe5bf3466e..e0f155a031 100644 --- a/website_docs/instrumentation.md +++ b/website_docs/instrumentation.md @@ -9,6 +9,7 @@ This guide will cover creating and annotating spans, creating and annotating met - [Creating Spans](#creating-spans) - [Attributes](#attributes) - [Semantic Attributes](#semantic-attributes) +- [Span Status](#span-status) ## Example Application @@ -168,3 +169,30 @@ function doWork(parent) { span.end(); } ``` + +## Span Status + +A status can be set on a span, to indicate if the traced operation has completed successfully (`Ok`) or with an `Error`. The default status is `Unset`. + +The status can be set at any time before the span is finished: + +```javascript +function doWork(parent) { + const span = tracer.startSpan('doWork', { + parent, + }); + span.setStatus({ + code: opentelemetry.SpanStatusCode.OK, + message: 'Ok.' + }) + for (let i = 0; i <= Math.floor(Math.random() * 40000000); i += 1) { + if(i > 10000) { + span.setStatus({ + code: opentelemetry.SpanStatusCode.ERROR, + message: 'Error.' + }) + } + } + span.end(); +} +``` \ No newline at end of file From 0167177c586b62bd2aad79b2073b48d6c3fd4cc8 Mon Sep 17 00:00:00 2001 From: svrnm Date: Thu, 5 Aug 2021 18:33:12 +0200 Subject: [PATCH 5/8] docs: fix markdown style issues --- website_docs/instrumentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website_docs/instrumentation.md b/website_docs/instrumentation.md index e0f155a031..57a4565fa8 100644 --- a/website_docs/instrumentation.md +++ b/website_docs/instrumentation.md @@ -195,4 +195,4 @@ function doWork(parent) { } span.end(); } -``` \ No newline at end of file +``` From 5dbf275b29c28eaa9ced313069c128c8b5e7dfac Mon Sep 17 00:00:00 2001 From: svrnm Date: Thu, 5 Aug 2021 18:43:53 +0200 Subject: [PATCH 6/8] docs: fix markdown style issues (2) --- website_docs/getting_started/nodejs.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/website_docs/getting_started/nodejs.md b/website_docs/getting_started/nodejs.md index 5dc83ef99f..21e3e70ff8 100644 --- a/website_docs/getting_started/nodejs.md +++ b/website_docs/getting_started/nodejs.md @@ -264,7 +264,7 @@ const meter = new MeterProvider({ }).getMeter('your-meter-name'); ``` -Now you can require this file from your application code and use the `Meter` to create and manage metrics. The simplest of these metrics is a counter. +Now you can require this file from your application code and use the `Meter` to create and manage metrics. The simplest of these metrics is a counter. Let's create and export from your `monitoring.js` file a middleware function that express can use to count all requests by route. Modify the `monitoring.js` file so it looks like this: @@ -331,7 +331,6 @@ Listening for requests on http://localhost:8080 Now, when you open in your web browser, you should see the metrics printed in the console by the `ConsoleMetricExporter`. - ```json { "name": "requests", @@ -342,4 +341,4 @@ Now, when you open in your web browser, you should see t } { "route": "/" } "value": "1" -``` \ No newline at end of file +``` From 659154b2d297af6fc4f4c4d470e8565a68c0d021 Mon Sep 17 00:00:00 2001 From: svrnm Date: Fri, 6 Aug 2021 15:47:05 +0200 Subject: [PATCH 7/8] docs: fix single quotes in JSON --- website_docs/getting_started/nodejs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website_docs/getting_started/nodejs.md b/website_docs/getting_started/nodejs.md index 21e3e70ff8..33adb9493f 100644 --- a/website_docs/getting_started/nodejs.md +++ b/website_docs/getting_started/nodejs.md @@ -335,7 +335,7 @@ Now, when you open in your web browser, you should see t { "name": "requests", "description": "Count all incoming requests", - "unit": '1', + "unit": "1", "metricKind": 0, "valueType": 1 } From 842da636c1003cf5a50d681af197ee7fac025799 Mon Sep 17 00:00:00 2001 From: Severin Neumann Date: Mon, 9 Aug 2021 19:27:10 +0200 Subject: [PATCH 8/8] Update _index.md --- website_docs/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website_docs/_index.md b/website_docs/_index.md index 99262d9b7a..859f8026cc 100644 --- a/website_docs/_index.md +++ b/website_docs/_index.md @@ -14,7 +14,7 @@ export data. | Signal | API Status | SDK Status | |---------|-------------|-------------------| -| Tracing | Stable | Release Candidate | +| Trace | Stable | Release Candidate | | Metrics | Development | Development | | Logs | Roadmap | Roadmap |