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

Update distributed tracing docs to include otel #1880

Merged
merged 1 commit into from
Nov 21, 2024
Merged
Changes from all 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
54 changes: 31 additions & 23 deletions linkerd.io/content/2-edge/tasks/distributed-tracing.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,21 @@ To install the Linkerd-Jaeger extension, run the command:
linkerd jaeger install | kubectl apply -f -
```

{{< note >}}
The Linkerd-Jaeger extension currently configures proxies to export traces
with the OpenCensus protocol by default for backwards compatibility. OpenCensus is
[sunset and no longer maintained](https://opentelemetry.io/blog/2023/sunsetting-opencensus/),
so we recommend installing the Linkerd-Jaeger extension with OpenTelemetry as the
proxy trace export protocol:

```bash
linkerd jaeger install --set webhook.collectorTraceProtocol=opentelemetry | kubectl apply -f
```

In the future, the default protocol will be changed to OpenTelemetry so this step
will no longer be necessary.
{{< /note >}}

You can verify that the Linkerd-Jaeger extension was installed correctly by
running:

Expand Down Expand Up @@ -80,7 +95,7 @@ information, this
[commit](https://github.com/BuoyantIO/emojivoto/commit/47a026c2e4085f4e536c2735f3ff3788b0870072)
shows how this was done. For most programming languages, it simply requires the
addition of a client library to take care of this. Emojivoto uses the OpenCensus
client, but others can be used.
client, but others should be used.

To enable tracing in emojivoto, run:

Expand All @@ -89,7 +104,8 @@ kubectl -n emojivoto set env --all deploy OC_AGENT_HOST=collector.linkerd-jaeger
```

This command will add an environment variable that enables the applications to
propagate context and emit spans.
propagate context and emit spans. In the meantime, the collector installed with
Linkerd-Jaeger will continue to support both protocols.

## Explore Jaeger

Expand Down Expand Up @@ -254,48 +270,40 @@ headers, it's usually much easier to use a library which does three things:
- Modifies the trace context (i.e. starts a new span)
- Transmits this data to a trace collector

We recommend using OpenCensus in your service and configuring it with:
We recommend using OpenTelemetry in your service and configuring it with:

- [b3 propagation](https://github.com/openzipkin/b3-propagation) (this is the
default)
- [the OpenCensus agent
exporter](https://opencensus.io/exporters/supported-exporters/go/ocagent/)
- [the OpenTelemetry agent
exporter](https://opentelemetry.io/docs/collector/deployment/agent/)

The OpenCensus agent exporter will export trace data to the OpenCensus collector
over a gRPC API. The details of how to configure OpenCensus will vary language
The OpenTelemetry agent exporter will export trace data to the OpenTelemetry collector
over a gRPC API. The details of how to configure OpenTelemetry will vary language
by language, but there are [guides for many popular
languages](https://opencensus.io/quickstart/). You can also see an end-to-end
example of this in Go with our example application,
[Emojivoto](https://github.com/adleong/emojivoto).

You may notice that the OpenCensus project is in maintenance mode and will
become part of [OpenTelemetry](https://opentelemetry.io/). Unfortunately,
OpenTelemetry is not yet production ready and so OpenCensus remains our
recommendation for the moment.
languages](https://opentelemetry.io/docs/languages/).

It is possible to use many other tracing client libraries as well. Just make
sure the b3 propagation format is being used and the client library can export
its spans in a format the collector has been configured to receive.

## Collector: OpenCensus
## Collector: OpenTelemetry

The OpenCensus collector receives trace data from the OpenCensus agent exporter
The OpenTelemetry collector receives trace data from the OpenTelemetry agent exporter
and potentially does translation and filtering before sending that data to
Jaeger. Having the OpenCensus exporter send to the OpenCensus collector gives us
a lot of flexibility: we can switch to any backend that OpenCensus supports
Jaeger. Having the OpenTelemetry exporter send to the OpenTelemetry collector gives
us a lot of flexibility: we can switch to any backend that OpenTelemetry supports
without needing to interrupt the application.

## Backend: Jaeger

Jaeger is one of the most widely used tracing backends and for good reason: it
is easy to use and does a great job of visualizing traces. However, [any backend
supported by OpenCensus](https://opencensus.io/service/exporters/) can be used
instead.
is easy to use and does a great job of visualizing traces. However, any backend
supported by OpenTelemetry can be used instead.

## Linkerd

If your application is injected with Linkerd, the Linkerd proxy will participate
in the traces and will also emit trace data to the OpenCensus collector. This
in the traces and will also emit trace data to the trace collector. This
enriches the trace data and allows you to see exactly how much time requests are
spending in the proxy and on the wire.

Expand Down
Loading