From 3a81389b938e87abc4dbfa19ddaf685c7f33bcea Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Tue, 14 Sep 2021 11:53:52 -0400 Subject: [PATCH] Drop website_docs folder (#2469) Co-authored-by: Daniel Dyla --- website_docs/_index.md | 32 --- website_docs/exporters.md | 111 -------- website_docs/getting_started/_index.md | 9 - website_docs/getting_started/browser.md | 238 ---------------- website_docs/getting_started/nodejs.md | 328 ----------------------- website_docs/instrumentation.md | 197 -------------- website_docs/instrumentation_examples.md | 28 -- 7 files changed, 943 deletions(-) delete mode 100644 website_docs/_index.md delete mode 100644 website_docs/exporters.md delete mode 100644 website_docs/getting_started/_index.md delete mode 100644 website_docs/getting_started/browser.md delete mode 100644 website_docs/getting_started/nodejs.md delete mode 100644 website_docs/instrumentation.md delete mode 100644 website_docs/instrumentation_examples.md diff --git a/website_docs/_index.md b/website_docs/_index.md deleted file mode 100644 index e0846eac64..0000000000 --- a/website_docs/_index.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Javascript -weight: 20 -description: >- - - A language-specific implementation of OpenTelemetry in JavaScript (for Node.JS & the browser). -cascade: - github_repo: &repo https://github.com/open-telemetry/opentelemetry-js - github_subdir: website_docs - path_base_for_github_subdir: content/en/docs/js/ - github_project_repo: *repo ---- - -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 - -| Signal | API Status | SDK Status | -|---------|-------------|-------------------| -| Trace | Stable | Release Candidate | -| Metrics | Development | Development | -| Logs | Roadmap | Roadmap | - -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) -- [API Reference](https://open-telemetry.github.io/opentelemetry-js-api) -- [SDK Reference](https://open-telemetry.github.io/opentelemetry-js) diff --git a/website_docs/exporters.md b/website_docs/exporters.md deleted file mode 100644 index 562b914e47..0000000000 --- a/website_docs/exporters.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: "Exporters" -weight: 3 ---- - -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: - -```shell -$ docker run -d --name jaeger \ - -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \ - -p 5775:5775/udp \ - -p 6831:6831/udp \ - -p 6832:6832/udp \ - -p 5778:5778 \ - -p 16686:16686 \ - -p 14268:14268 \ - -p 14250:14250 \ - -p 9411:9411 \ - jaegertracing/all-in-one:latest -``` - -Install the exporter package as a dependency for your application: - -```shell -npm install --save @opentelemetry/exporter-jaeger -``` - -Update your opentelemetry configuration to use the exporter and to send data to your jaeger backend: - -```javascript -const { JaegerExporter } = require("@opentelemetry/exporter-jaeger"); -const { BatchSpanProcessor } = require("@opentelemetry/tracing"); - -provider.addSpanProcessor(new BatchSpanProcessor(new JaegerExporter())) -``` - -## Zipkin - -To set up Zipkin as quickly as possible, run it in a docker container: - -```shell -docker run --rm -d -p 9411:9411 --name zipkin openzipkin/zipkin -``` - -Install the exporter package as a dependency for your application: - -```shell -npm install --save @opentelemetry/exporter-zipkin -``` - -Update your opentelemetry configuration to use the exporter and to send data to your zipkin backend: - -```javascript -const { ZipkinExporter } = require("@opentelemetry/exporter-zipkin"); -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 -telemetry data follow the instructions to setup a [OpenTelemetry collector](https://opentelemetry.io/docs/collector/) diff --git a/website_docs/getting_started/_index.md b/website_docs/getting_started/_index.md deleted file mode 100644 index 3ab3b1ca5f..0000000000 --- a/website_docs/getting_started/_index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -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) diff --git a/website_docs/getting_started/browser.md b/website_docs/getting_started/browser.md deleted file mode 100644 index 65429d4713..0000000000 --- a/website_docs/getting_started/browser.md +++ /dev/null @@ -1,238 +0,0 @@ ---- -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. - -- [Example Application](#example-application) - - [Installation](#installation) - - [Initialization and Configuration](#initialization-and-configuration) - - [Creating a Tracer Provider](#creating-a-tracer-provider) - - [Creating an Exporter](#creating-an-exporter) - - [Add Instrumentations](#add-instrumentations) -- [Meta Packages for Web](#meta-packages-for-web) -- [Instrumentation with Browser Extension](#instrumentation-with-browser-extension) - -## Example Application - -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 - - - - - Document Load Instrumentation Example - - - - - - - Example of using Web Tracer with document load instrumentation with console exporter and collector exporter - - -``` - -### Installation - -To create traces in the browser, you will need `@opentelemetry/sdk-trace-web`, and the instrumentation `@opentelemetry/instrumentation-document-load`: - -```shell -npm init -y -npm install --save @opentelemetry/api @opentelemetry/sdk-trace-web @opentelemetry/instrumentation-document-load @opentelemetry/context-zone -``` - -### 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 - -``` - -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 instrumentaion to trace document load: - -```javascript -import { WebTracerProvider } from '@opentelemetry/sdk-trace-web'; -import { DocumentLoadInstrumentation } from '@opentelemetry/instrumentation-document-load'; -import { ZoneContextManager } from '@opentelemetry/context-zone'; -import { registerInstrumentations } from '@opentelemetry/instrumentation'; - -const provider = new WebTracerProvider(); - -provider.register({ - // Changing default contextManager to use ZoneContextManager - supports asynchronous operations - optional - contextManager: new ZoneContextManager(), -}); - -// Registering instrumentations -registerInstrumentations({ - instrumentations: [ - new DocumentLoadInstrumentation(), - ], -}); -``` - -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 - -### Creating an Exporter - -In the following example, we will use the `ConsoleSpanExporter` which prints all spans to the console. - -In order to visualize and analyze your traces, you will need to export them to a tracing backend. -Follow [these instructions](../exporters.md) for setting up a backend and exporter. - -You may also want to use the `BatchSpanProcessor` to export spans in batches in order to more efficiently use resources. - -To export traces to the console, modify `document-load.js` so that it matches the following code snippet: - -```javascript -import { ConsoleSpanExporter, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base'; -import { WebTracerProvider } from '@opentelemetry/sdk-trace-web'; -import { DocumentLoadInstrumentation } from '@opentelemetry/instrumentation-document-load'; -import { ZoneContextManager } from '@opentelemetry/context-zone'; -import { registerInstrumentations } from '@opentelemetry/instrumentation'; - -const provider = new WebTracerProvider(); -provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter())); - -provider.register({ - // Changing default contextManager to use ZoneContextManager - supports asynchronous operations - optional - contextManager: new ZoneContextManager(), -}); - -// Registering instrumentations -registerInstrumentations({ - instrumentations: [ - new DocumentLoadInstrumentation(), - ], -}); -``` - -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 - ] - } - ] -} -``` - -### Add Instrumentations - -If you want to instrument AJAX requests, User Interactions and others, you can register additional instrumentations for those: - -```javascript -registerInstrumentations({ - instrumentations: [ - new UserInteractionInstrumentation(), - new XMLHttpRequestInstrumentation() - ], -}); -``` - -## Meta Packages for Web - -To leverage the most common instrumentations all in one you can simply use the -[OpenTelemetry Meta Packages for Web](https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-web) - -## Instrumentation with Browser Extension - -If you'd like to quickly preview what OpenTelemetry instrumentation would look like with your website (or any other site) -installed, you can use the [OpenTelemetry Browser Extension](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/packages/opentelemetry-browser-extension-autoinjection) diff --git a/website_docs/getting_started/nodejs.md b/website_docs/getting_started/nodejs.md deleted file mode 100644 index 2054e320e4..0000000000 --- a/website_docs/getting_started/nodejs.md +++ /dev/null @@ -1,328 +0,0 @@ ---- -title: "Node.JS" -weight: 2 ---- - -This guide will show you how to get started with tracing in Node.js. - -- [Example Application](#example-application) - - [Dependencies](#dependencies) - - [Code](#code) -- [Tracing](#tracing) - - [Dependencies](#dependencies-1) - - [Core Dependencies](#core-dependencies) - - [Exporter](#exporter) - - [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 - -This is a small example application we will monitor in this guide. - -### Dependencies - -Install dependencies used by the example. - -```sh -npm install express -``` - -### Code - -Please save the following code as `app.js`. - -```javascript -/* app.js */ - -const express = require("express"); - -const PORT = process.env.PORT || "8080"; -const app = express(); - -app.get("/", (req, res) => { - res.send("Hello World"); -}); - -app.listen(parseInt(PORT, 10), () => { - console.log(`Listening for requests on http://localhost:${PORT}`); -}); -``` - -Run the application with the following request and open in your web browser to ensure it is working. - -```sh -$ node app.js -Listening for requests on http://localhost:8080 -``` - -## Tracing - -### Dependencies - -The following dependencies are required to trace a Node.js application. - -#### Core Dependencies - -These dependencies are required to configure the tracing SDK and create spans. - -```shell -npm install @opentelemetry/sdk-node @opentelemetry/api -``` - -#### Exporter - -In the following example, we will use the `ConsoleSpanExporter` which prints all spans to the console. - -In order to visualize and analyze your traces, you will need to export them to a tracing backend. -Follow [these instructions](../exporters.md) for setting up a backend and exporter. - -You may also want to use the `BatchSpanProcessor` to export spans in batches in order to more efficiently use resources. - -#### Instrumentation Modules - -Many common modules such as the `http` standard library module, `express`, and others can be automatically instrumented using autoinstrumentation modules. To find autoinstrumenatation modules, you can look at the [registry](https://opentelemetry.io/registry/?language=js&component=instrumentation#). - -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. - -Create a file with a name like `tracing.js` which will contain your tracing setup code. - -```javascript -/* tracing.js */ - -// Require dependencies -const opentelemetry = require("@opentelemetry/sdk-node"); -const { getNodeAutoInstrumentations } = require("@opentelemetry/auto-instrumentations-node"); - -const sdk = new opentelemetry.NodeSDK({ - traceExporter: new opentelemetry.tracing.ConsoleSpanExporter(), - instrumentations: [getNodeAutoInstrumentations()] -}); - -sdk.start() -``` - -### Run Application - -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 -``` - -Open 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`. - -
-View example output - -```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" - }, - "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" - }, - "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" - }, - "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" - }, - "status": { "code": 1 }, - "events": [] -} -``` - -
- -## 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" -``` diff --git a/website_docs/instrumentation.md b/website_docs/instrumentation.md deleted file mode 100644 index a6376e68e2..0000000000 --- a/website_docs/instrumentation.md +++ /dev/null @@ -1,197 +0,0 @@ ---- -title: "Instrumentation" -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) -- [Span Status](#span-status) - -## Example Application - -In the following this guide will use the following sample app: - -```javascript -'use strict'; - -for (let i = 0; i < 10; i += 1) { - doWork(); -} - -function doWork() { - console.log("work...") - // simulate some random work. - for (let i = 0; i <= Math.floor(Math.random() * 40000000); i += 1) { - } -} -``` - -## Creating Spans - -As you have learned in the previous [Getting Started](../getting_started/) guide you need a TracerProvider and an Exporter. Install the dependencies and add them to head of your application code to get started: - -```shell -npm install @opentelemetry/sdk-trace-base -``` - -```javascript -const { BasicTracerProvider, ConsoleSpanExporter, SimpleSpanProcessor } = require('@opentelemetry/sdk-trace-base'); - -const provider = new BasicTracerProvider(); - -// Configure span processor to send spans to the exporter -provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter())); - -provider.register(); -``` - -Next, initialize the OpenTelemetry APIs to use the BasicTracerProvider bindings. -This registers the tracer provider with the OpenTelemetry API as the global tracer provider. -This means when you call API methods like `opentelemetry.trace.getTracer`, they will use this tracer provider. -If you do not register a global tracer provider, instrumentation which calls these methods will receive no-op implementations - -Install the required package and modify your code: - -```shell -npm install @opentelemetry/api -``` - -```javascript -const opentelemetry = require('@opentelemetry/api'); -const tracer = opentelemetry.trace.getTracer('example-basic-tracer-node'); -``` - -Add a first span to the sample application. Modify your code like the following: - -```javascript -// Create a span. A span must be closed. -const parentSpan = tracer.startSpan('main'); -for (let i = 0; i < 10; i += 1) { - doWork(parentSpan); -} -// Be sure to end the span. -parentSpan.end(); -``` - -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": [] -} -``` - -Add further spans into the `doWork` method: - -```javascript -// Create a span. A span must be closed. -const parentSpan = tracer.startSpan('main'); -for (let i = 0; i < 10; i += 1) { - doWork(parentSpan); -} - -/* ... */ - -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 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. - -## Attributes - -Attributes can be used to describe your spans. Attributes can be added to a span at any time before the span is finished: - -```javascript -function doWork(parent) { - 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 - } - span.setAttribute('attribute2', 'value2'); - span.end(); -} -``` - -### 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. - -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 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 - } - span.setAttribute(SemanticAttributes.CODE_FILEPATH, __filename); - 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 ctx = opentelemetry.trace.setSpan(opentelemetry.context.active(), parent); - const span = tracer.startSpan('doWork', undefined, ctx); - - 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(); -} -``` diff --git a/website_docs/instrumentation_examples.md b/website_docs/instrumentation_examples.md deleted file mode 100644 index cd3fbbb733..0000000000 --- a/website_docs/instrumentation_examples.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: "Instrumentation Examples" -weight: 4 ---- - -Here are Some of the resources for Opentelemetry Instrumentation Examples - -## Core Examples - -The repository of the [JavaScript version of OpenTelemetry](https://github.com/svrnm/opentelemetry-js) holds some -[examples](https://github.com/svrnm/opentelemetry-js/tree/main/examples) of how to run real application with OpenTelemetry JavaScript. - -## Plugin & Package Examples - -Many of the packages and plugins at the [repository for OpenTelemetry JavaScript](https://github.com/open-telemetry/opentelemetry-js-contrib/) -contributions come with an usage example. You can find them in the [examples folder](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/examples). - -## Community Resources - -### nodejs-opentelemetry-tempo - -Project demonstrating Complete Observability Stack utilizing [Prometheus](https://prometheus.io/), [Loki](https://grafana.com/oss/loki/) (_For distributed logging_), [Tempo](https://grafana.com/oss/tempo/) (_For Distributed tracing, this basically uses Jaeger Internally_), [Grafana](https://grafana.com/grafana/) for **NodeJs** based applications (_With OpenTelemetry auto / manual Instrumentation_) involving microservices with DB interactions. - -Checkout [nodejs-opentelemetry-tempo](https://github.com/mnadeem/nodejs-opentelemetry-tempo) and get started - -```bash -docker-compose up --build -```