[Operator] Add docs for instrumenting Deno #5962
Conversation
|
TIL that deno comes with otel support, wow! We normally default to not allow documentation for non official otel projects, e.g. we have https://opentelemetry.io/docs/languages/other/ to list 3rd party implementations and language interest (which needs some love and attention from what I just see), but having a language provide out of the box support is very much in line with otel's mission & vision, so we should address that accordingly. @lucacasonato thank you for bringing this to our attention, we need some time to think about that and address this properly. cc @open-telemetry/governance-committee @open-telemetry/technical-committee |
| ### Deno | ||
|
|
||
| The following command creates a basic Instrumentation resource that is | ||
| configured for instrumenting Deno services. |
There was a problem hiding this comment.
| configured for instrumenting Deno services. | |
| configured for instrumenting [Deno](https://deno.com/) services. |
|
|
||
| {{% alert title="Note" color="info" %}} | ||
|
|
||
| Deno's OpenTelemetry integration is not yet stable. As a result all workloads |
There was a problem hiding this comment.
| Deno's OpenTelemetry integration is not yet stable. As a result all workloads | |
| [Deno's OpenTelemetry integration][deno-otel-docs] is not yet stable. As a result all workloads |
Note that I define [deno-otel-docs] further below.
| By default, the Deno OpenTelemetry integration captures `console.log` output as | ||
| logs, while still printing the logs to stdout / stderr. There are two other | ||
| behaviours that can be configured: |
There was a problem hiding this comment.
| By default, the Deno OpenTelemetry integration captures `console.log` output as | |
| logs, while still printing the logs to stdout / stderr. There are two other | |
| behaviours that can be configured: | |
| By default, the Deno OpenTelemetry integration exports `console.log()` output as | |
| [logs](/docs/concepts/signals/logs/), while still printing the logs to stdout / stderr. You can configure these alternative behaviors: |
|
|
||
| {{% /alert %}} | ||
|
|
||
| #### Configuring console.log capturing in Deno |
There was a problem hiding this comment.
| #### Configuring console.log capturing in Deno | |
| #### Configuration options |
| - `OTEL_DENO_CONSOLE=replace`: capture `console.log` output as logs and do not | ||
| print to stdout / stderr. |
There was a problem hiding this comment.
| - `OTEL_DENO_CONSOLE=replace`: capture `console.log` output as logs and do not | |
| print to stdout / stderr. | |
| - `OTEL_DENO_CONSOLE=replace`: only export `console.log()` output as logs; do not | |
| print to stdout / stderr. |
|
|
||
| - `OTEL_DENO_CONSOLE=replace`: capture `console.log` output as logs and do not | ||
| print to stdout / stderr. | ||
| - `OTEL_DENO_CONSOLE=ignore`: do not capture `console.log` output as logs. |
There was a problem hiding this comment.
| - `OTEL_DENO_CONSOLE=ignore`: do not capture `console.log` output as logs. | |
| - `OTEL_DENO_CONSOLE=ignore`: do not export `console.log()` output as logs. |
Question: does ignore imply that the output is completely ignored, and hence output isn't printed either? If so then the statement should probably be:
| - `OTEL_DENO_CONSOLE=ignore`: do not capture `console.log` output as logs. | |
| - `OTEL_DENO_CONSOLE=ignore`: neither export as logs nor print `console.log()` output. |
| For more details, see | ||
| [Deno's documentation on the OpenTelemetry integration](https://docs.deno.com/runtime/fundamentals/open_telemetry/). |
There was a problem hiding this comment.
| For more details, see | |
| [Deno's documentation on the OpenTelemetry integration](https://docs.deno.com/runtime/fundamentals/open_telemetry/). | |
| For more details, see Deno's [OpenTelemetry integration][deno-otel-docs] documentation. | |
| [deno-otel-docs]: https://docs.deno.com/runtime/fundamentals/open_telemetry/ |
| @@ -684,13 +746,21 @@ Here are a few things to check for: | |||
| - **Is the auto-instrumentation for the right language?** For example, when | |||
| instrumenting a Python application, make sure that the annotation doesn't | |||
| incorrectly say `instrumentation.opentelemetry.io/inject-java: "true"` | |||
| instead. | |||
| instead. | |||
There was a problem hiding this comment.
Why this whitespace change? It should be undone, though the formatter should have fixed / reported it.
| {{% alert title="Note" color="info" %}} | ||
|
|
||
| Note that unlike other auto-instrumentation, the Deno auto-instrumentation uses | ||
| the `instrumentation.opentelemetry.io/inject-sdk: "true"` annotation, not an | ||
| annotation that contains the string `deno`. | ||
|
|
||
| {{% /alert %}} | ||
|
|
There was a problem hiding this comment.
I'd rather drop this alert and fold this alert text into a sub-bullet of Is the auto-instrumentation for the right language?, which already mentions exceptions (currently for Python). For example, consider replacing the bullet at line 746 of this PR (line 684 in the original file), with:
- **Is the auto-instrumentation for the right language?** For example, when instrumenting an application in:
- Deno, which uses the `instrumentation.opentelemetry.io/inject-sdk: "true"` annotation, rather than an annotation containing the string `deno`.
- Python: ensure that the annotation doesn't incorrectly say `instrumentation.opentelemetry.io/inject-java: "true"` instead.@open-telemetry/docs-approvers WDYT?
|
Let's keep the sections in alphabetical order: @lucacasonato - could you please move the Go section to be right after the new Deno section? |
Also see open-telemetry/opentelemetry-operator#3613
This adds documentation for using the operator to instrument Deno applications by setting
OTEL_DENO=trueand then injecting withinstrumentation.opentelemetry.io/inject-sdk: "true".cc @jaronoff97
Preview: https://deploy-preview-5962--opentelemetry.netlify.app/docs/kubernetes/operator/automatic/#deno