7.9 KiB

Raw Blame History

Documenting Instrumentation

Due to the large number of instrumentations supported in this project, it is important to maintain a consistent documentation approach. We use structured metadata files and README.md files along with tooling and automation to both generate and audit documentation.

This document outlines the documentation aspirations for this project. Not all instrumentations will meet all of these guidelines or already be documented in this way.

README.md Files for Library Instrumentations

Every library instrumentation module must have a README.md file in the library directory root (instrumentation/{some instrumentation}/library/README.md) that follows this pattern:

# Library Instrumentation for [Technology] version [X.Y] and higher

Provides OpenTelemetry instrumentation for [Technology link].

[Any other relevant context about the instrumentation]

## Quickstart

### Add these dependencies to your project

Replace `OPENTELEMETRY_VERSION` with the [latest release](maven-central-link).

For Maven, add to your `pom.xml` dependencies:

    ```xml
    <dependencies>
      <dependency>
        <groupId>io.opentelemetry.instrumentation</groupId>
        <artifactId>{library artifact name}</artifactId>
        <version>OPENTELEMETRY_VERSION</version>
      </dependency>
    </dependencies>
    ```

For Gradle, add to your dependencies:

    ```kotlin
    implementation("io.opentelemetry.instrumentation:{library artifact name}:OPENTELEMETRY_VERSION")
    ```

### Usage

[Code examples showing integration]

Following these sections, you can include any other relevant information.

If there is a difference in functionality between the library and javaagent instrumentation, it is important to document these differences.

README.md Files for Javaagent Instrumentations

Every javaagent instrumentation module should have a README.md file in the javaagent directory root (instrumentation/{some instrumentation}/javaagent/README.md) that follows this pattern:

# [Technology] Instrumentation

[Brief description of what the instrumentation does and what versions it applies to]

## Settings
| System property | Type | Default | Description |
|-----------------|------|---------|-------------|
| `property.name` | Type | Default | Description |

Note: At some point we will likely automate the generation of this javaagent README.md file using the metadata.yaml file described below.

Metadata.yaml Files

Each instrumentation should have a metadata.yaml file in the root of the instrumentation directory (instrumentation/{some instrumentation}/metadata.yaml) that contains structured metadata about the instrumentation.

Description (required)

At a minimum, every instrumentation metadata file should include a description.

Some example descriptions:

This instrumentation enables SERVER spans and metrics for the ActiveJ HTTP server.
This instrumentation provides context propagation for Akka actors, it does not emit any telemetry on its own.
The Alibaba Druid instrumentation generates database connection pool metrics for druid data sources.
The Apache Dubbo instrumentation provides CLIENT and SERVER spans for Apache Dubbo RPC calls. Each call produces a span named after the Dubbo method, enriched with standard RPC attributes (system, service, method), network attributes, and error details if an exception occurs.

Some notes when writing descriptions:

You don't always need to explicitly name the instrumentation, and you can start with "This instrumentation..."
Prefer the convention of using the word "enables" when describing what the instrumentation does, "This instrumentation enables SERVER spans and metrics for the ActiveJ" instead of something like "This instrumentation provides SERVER spans and metrics for the ActiveJ".
Explicitly state whether the instrumentation generates new telemetry (spans, metrics, logs).
- If it doesn't generate new telemetry, clearly explain what it's purpose is, for example whether it augments or enriches existing telemetry produced by other instrumentations (e.g., by adding attributes or ensuring context propagation).
Do not include specific method names, class names, or other low-level implementation details in the description unless they are essential to understanding the purpose of the instrumentation.
It is not usually necessary to include specific library or framework version numbers in the description, unless that context is significant in some way.
When an instrumentation generates spans, be specific about the SpanKind (e.g., SERVER, CLIENT, PRODUCER, CONSUMER, INTERNAL).
- Capitalize SpanKind values (e.g., SERVER, CLIENT) when used in descriptions.

Configurations

If an instrumentation module has configuration options, they should be documented in the configurations section of the metadata.yaml file.

Each configuration should include:

name: The full configuration property name, for example otel.instrumentation.common.db-statement-sanitizer.enabled.
description: A brief description of what the configuration does.
type: The data type of the configuration value. Supported types are: boolean, string, list, and map.
default: The default value for the configuration.

If a configuration enables experimental attributes, list them, for example:

Enables experimental span attributes couchbase.operation_id and couchbase.local.address.

Classification (optional)

If an instrumentation module does not specify a classification, it is assumed to be library.

There are currently three supported classifications:

library: An instrumentation that provides automatic instrumentation for a specific library or framework. This is the default classification.
internal: An instrumentation that is used internally by other instrumentations or the OpenTelemetry SDK itself, and is not intended for direct use by end users.
custom: An instrumentation that is intended for custom or user-defined use cases, and may not fit into the standard library or internal categories.

The primary way this classification is used is to group and filter instrumentations by their utility in tooling and documentation. If you are unsure which classification to use, you can omit this field, and it will default to library.

Disabled by Default (optional)

If an instrumentation is disabled by default, set disabled_by_default: true. This indicates that the instrumentation will not be active unless explicitly enabled by the user. If this field is omitted, it defaults to false, meaning the instrumentation is enabled by default.

Instrumentation List (docs/instrumentation-list.md)

The contents of the metadata.yaml files are combined with other information about the instrumentation to generate a complete catalog of instrumentations in docs/instrumentation-list.md. This file is generated via a gradle task and should not be edited directly (see this readme for more information on this process).

If you are submitting new instrumentation or updating existing instrumentation, you do not need to update this file unless you want to, as it can take a significant amount of time to run (40+ minutes). Each night a GitHub Action runs to regenerate this file based on the current state of the repository, so all changes will be reflected within 24 hours.

opentelemetry.io

All of our instrumentation modules are listed on the opentelemetry.io website in the context of how to suppress specific instrumentation.

All new instrumentations should be added to this list. There is a Github action that runs nightly to check for any missing instrumentations, and will open an issue if any are found.

7.9 KiB Raw Blame History