OpenTelemetry automatic and manual instrumentation

An application can be instrumented with OpenTelemetry either automatically or manually.

• With automatic instrumentation, the API and SDK takes the configuration provided (through code or environment variables) and does most of the work automatically (for example, starting and ending spans).
• Manual instrumentation, while requiring more work on the user/developer side, enables far more options for customization, from naming various components within OpenTelemetry (for example, spans and the tracer) to adding your own attributes, specific exception handling, and more.

Whether you choose automatic or manual instrumentation, downloading and/or importing the official OpenTelemetry dependencies is your first step.

OpenTelemetry offers different repositories for instrumenting each implemented language.

• In many cases, the Core repository provides an API and SDK implementation and can be used to manually instrument your application.
• An Instrumentation repository might provide all of the functionality the Core repository provides, plus an automatic instrumentation for a variety of libraries and frameworks.
• Optional components, as well as frameworks and vendor instrumentations can usually be found in the Contrib repository.

However, some instrumentation libraries combine manual and automatic instrumentation in one repository (for example, Ruby), while others might offer both, including separate core components in separate repositories (for example, JavaScript).

The exact installation will also vary depending on the language, but there are similarities.

Automatic instrumentation

Dynatrace recommends that you use automatic instrumentation as much as possible. Due to its simplicity of use, automatic instrumentation decreases the potential for error and can provide a great entry into distributed tracing.

We recommend manual instrumentation when data is missing or you need greater customization. When using manual instrumentation, be sure to follow the semantic conventions.

To instrument automatically

1. Add the dependencies you need.
   • At least one, and usually multiple, dependencies are needed to enable automatic instrumentation. Those will add the API and SDK capabilities.
   • Other dependencies, like an exporter or language-specific instrumentation dependencies, might also be necessary.
2. Configure the OpenTelemetry instrumentation.
   • Specific configuration can be done via environment variables. In other cases, such as Java, you can also rely on language-specific means such as system properties.
   • The minimum configuration required is a service.name to enable identification of the service being instrumented. Other options include data source specific configuration, exporter or resource configuration, and others.

Manual instrumentation

While manual instrumentation requires more work than automatic instrumentation, it provides a much greater deal of customization and specialized information about your application.

To enable manual instrumentation

1. Import the API and SDK. Nothing will work without importing OpenTelemetry into your code.
   • If you are building a library, the API dependency will suffice.
   • For standalone processes, both the API and SDK dependencies are necessary.
2. Configure the API. With the API imported into your code, you can set up a tracer provider or meter provider.
   • We recommend that the SDK provide a single default provider for these objects. That default provider would then create a tracer or meter instance and supply a service.name as well as a service.version.
   • The names you give here will span across spans and metric events alike.
3. Configure the SDK.
   • The SDK configuration will supply options for exporting your telemetry data to some form of backend.
   • We recommend that you write a configuration file for this.
4. Create telemetry data.
   • Traces and metric events can then be created through the tracer and meter objects the default provider has created. A plugin or other integrations to create these objects for you can be utilized as well.
   • The registry can give you more information on these.
5. Export data. There are two ways to export the telemetry data you have created:
   • Directly from a process. This approach requires an additional dependency import on one or more exporters, as well as libraries that translate the in-memory span and metric objects into the appropriate format for your analysis tool. You can always choose OTLP, as the data format is widely supported by all OpenTelemetry SDKs. It can also be sent to a collector.
   • Proxying through the collector. The collector is a proxy that can receive data in a variety of formats and send it to one or more backends of your choosing.