199 lines
8.5 KiB
Markdown
199 lines
8.5 KiB
Markdown
# 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:
|
|
|
|
```markdown
|
|
# 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:
|
|
|
|
```markdown
|
|
# [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.
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
description: "This instrumentation enables..."
|
|
disabled_by_default: true
|
|
classification: library
|
|
library_link: https://github.com/...
|
|
configurations:
|
|
- name: otel.instrumentation.common.db-statement-sanitizer.enabled
|
|
description: Enables statement sanitization for database queries.
|
|
type: boolean
|
|
default: true
|
|
```
|
|
|
|
### Description (required)
|
|
|
|
At a minimum, every instrumentation metadata file should include a `description`.
|
|
|
|
Some example descriptions:
|
|
|
|
* This instrumentation enables HTTP server spans and HTTP server 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 RPC client spans and RPC 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** HTTP server spans and HTTP server metrics for the ActiveJ" instead
|
|
of something like "This instrumentation **provides** HTTP server spans and HTTP server 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).
|
|
* When describing the functionality of the instrumentation and the telemetry, specify using
|
|
[semantic convention categories](https://opentelemetry.io/docs/specs/semconv/) when possible
|
|
(e.g., "database client spans", "RPC server metrics", "consumer messaging spans").
|
|
* 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.
|
|
|
|
### Library Link
|
|
|
|
For library instrumentations, include a `library_link` field with a URL to the library or framework's
|
|
main website or documentation, or if those don't exist, the GitHub repository.
|
|
|
|
### 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](../../instrumentation-docs/readme.md) 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](../../.github/workflows/metadata-update.yml) 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](https://opentelemetry.io/docs/zero-code/java/agent/disable/#suppressing-specific-agent-instrumentation).
|
|
|
|
All new instrumentations should be added to this list. There is a
|
|
[Github action](../../.github/workflows/documentation-disable-list-audit.yml) that runs nightly to check
|
|
for any missing instrumentations, and will open an issue if any are found.
|