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

Additional website docs updates #2344

Merged
merged 16 commits into from
Jul 28, 2021
Merged
Show file tree
Hide file tree
Changes from 6 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 70 additions & 0 deletions website_docs/exporters.md
Original file line number Diff line number Diff line change
@@ -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/)
56 changes: 47 additions & 9 deletions website_docs/getting_started/browser.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 Plugins](#add-plugins)
svrnm marked this conversation as resolved.
Show resolved Hide resolved
- [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)

Expand Down Expand Up @@ -38,7 +45,7 @@ Copy the following file into an empty directory and call it `index.html`.
</html>
```

## Installation
### Installation

To create traces in the browser, you will need `@opentelemetry/web`, and the plugin `@opentelemetry/plugin-document-load`:
svrnm marked this conversation as resolved.
Show resolved Hide resolved

Expand All @@ -47,7 +54,7 @@ npm init -y
npm install --save @opentelemetry/web @opentelemetry/instrumentation-document-load @opentelemetry/context-zone
svrnm marked this conversation as resolved.
Show resolved Hide resolved
```

## 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:

Expand All @@ -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 plugin to trace document load:

Expand Down Expand Up @@ -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';
Expand Down Expand Up @@ -199,3 +213,27 @@ Now, rebuild your application and open the browser again. In the console of the
]
}
```

### Add Plugins

If you want to instrument AJAX requests, User Interactions and others, you can add plugins to your
instrumentation:

```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 get a quick preview on how your website (or any other site) would look like with OpenTelemetry
svrnm marked this conversation as resolved.
Show resolved Hide resolved
installed, you can use the [OpenTelemetry Browser Extension](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/packages/opentelemetry-browser-extension-autoinjection)
14 changes: 6 additions & 8 deletions website_docs/getting_started/nodejs.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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 */
Expand Down
24 changes: 22 additions & 2 deletions website_docs/instrumentation_examples.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -13,6 +23,16 @@ 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
```

### otlp-logzio-fullstack

This is a Fullstack playground of Opentelemetry in Javascript, Javascript in Browsers and Node.js

Checkout [otlp-logzio-fullstack](https://github.com/niko-achilles/otlp-logzio-fullstack) and get started
svrnm marked this conversation as resolved.
Show resolved Hide resolved

```bash
docker-compose up --build
````
```