Instrumentation documentation guidelines (#14598)
Co-authored-by: Trask Stalnaker <trask.stalnaker@gmail.com>
This commit is contained in:
Jay DeLuca
GitHub
parent
ce4fb5093f
commit
68fdead509
|
|
@ -0,0 +1,180 @@
|
|||
# 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.
|
||||
|
||||
### 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](../../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.
|
||||
|
|
@ -69,15 +69,6 @@ include(":instrumentation:yarpc-1.0:library")
|
|||
include(":instrumentation:yarpc-1.0:testing")
|
||||
```
|
||||
|
||||
### Instrumentation metadata.yaml (Experimental)
|
||||
|
||||
Each module can contain a `metadata.yaml` file that describes the instrumentation. This information
|
||||
is then used when generating the [instrumentation-list.yaml](../instrumentation-list.yaml) file.
|
||||
The schema for `metadata.yaml` is still in development and may change in the future. See the
|
||||
[instrumentation-docs readme](../../instrumentation-docs/readme.md) for more information and the
|
||||
latest schema.
|
||||
|
||||
|
||||
### Instrumentation Submodules
|
||||
|
||||
When writing instrumentation that requires submodules for different versions, the name of each
|
||||
|
|
@ -344,6 +335,11 @@ code, see [this section](#writing-java-agent-unit-tests).
|
|||
|
||||
## Additional considerations regarding instrumentations
|
||||
|
||||
### Documentation
|
||||
|
||||
All new instrumentation modules should include relevant documentation. See our docs on
|
||||
[Documenting Instrumentation](documenting-instrumentation.md) for more details.
|
||||
|
||||
### Instrumenting code that is not available as a Maven dependency
|
||||
|
||||
If an instrumented server or library jar isn't available in any public Maven repository you can
|
||||
|
|
|
|||
Loading…
Reference in New Issue