diff --git a/website_docs/exporters.md b/website_docs/exporters.md new file mode 100644 index 0000000000..c1ce99369a --- /dev/null +++ b/website_docs/exporters.md @@ -0,0 +1,70 @@ +--- +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. + +Below you will find some introductions on how to setup backends and the matching exporters. + +## 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())) +``` + +## 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/browser.md b/website_docs/getting_started/browser.md index 664c09959e..2136368c84 100644 --- a/website_docs/getting_started/browser.md +++ b/website_docs/getting_started/browser.md @@ -3,11 +3,18 @@ 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. Here is an overview of what we will be doing. +This guide uses the example application in HTML & javascript provided below, but the steps to instrument your own application should be broadly the same. -- 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) +- [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) @@ -38,16 +45,16 @@ Copy the following file into an empty directory and call it `index.html`. ``` -## Installation +### Installation To create traces in the browser, you will need `@opentelemetry/web`, and the instrumentation `@opentelemetry/instrumentation-document-load`: ```shell npm init -y -npm install --save @opentelemetry/web @opentelemetry/instrumentation-document-load @opentelemetry/context-zone +npm install --save @opentelemetry/api @opentelemetry/web @opentelemetry/instrumentation-document-load @opentelemetry/context-zone ``` -## Initialization and Configuration +### 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: @@ -57,7 +64,7 @@ Create a empty file called `document-load.js` and add the following code to your We will add some code that will trace the document load timings and output those as OpenTelemetry Spans. -## Creating a Tracer Provider +### 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: @@ -94,9 +101,16 @@ and open the development webserver (e.g. at `http://localhost:1234`) to see if y There will be no output of traces yet, for this we need to add an exporter -## Creating a Console 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. -To export traces, modify `document-load.js` so that it matches the following code snippet: +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/tracing'; @@ -199,3 +213,26 @@ Now, rebuild your application and open the browser again. In the console of the ] } ``` + +### 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 index 73cbf1f2af..92ef2c1be9 100644 --- a/website_docs/getting_started/nodejs.md +++ b/website_docs/getting_started/nodejs.md @@ -72,14 +72,12 @@ These dependencies are required to configure the tracing SDK and create spans. #### Exporter -In order to visualize and analyze your traces, you will need to export them to a tracing backend such as Jaeger. OpenTelemetry JS provides exporters for some common open source tracing backends. +In the following example, we will use the `ConsoleSpanExporter` which prints all spans to the console. -- Jaeger - `@opentelemetry/exporter-jaeger` -- Zipkin - `@opentelemetry/exporter-zipkin` -- OpenTelemetry Protocol - - GRPC - `@opentelemetry/exporter-collector-grpc` - - Protobuf/HTTP - `@opentelemetry/exporter-collector-proto` - - JSON/HTTP - `@opentelemetry/exporter-collector` +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 @@ -91,7 +89,7 @@ You can also install all instrumentations maintained by the OpenTelemetry author 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. In this example, we will use the `ConsoleSpanExporter` which prints all spans to the console. In your application, you should use the exporter which goes with the tracing backend of your choice. You may also want to use the `BatchSpanProcessor` to export spans in batches in order to more efficiently use resources. +Create a file with a name like `tracing.js` which will contain your tracing setup code. ```javascript /* tracing.js */ diff --git a/website_docs/instrumentation_examples.md b/website_docs/instrumentation_examples.md index 19b3c5535a..cd3fbbb733 100644 --- a/website_docs/instrumentation_examples.md +++ b/website_docs/instrumentation_examples.md @@ -5,6 +5,16 @@ 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 @@ -13,6 +23,6 @@ Project demonstrating Complete Observability Stack utilizing [Prometheus](https: Checkout [nodejs-opentelemetry-tempo](https://github.com/mnadeem/nodejs-opentelemetry-tempo) and get started -````bash +```bash docker-compose up --build -```` +```