Skip to content

Latest commit

 

History

History
97 lines (72 loc) · 3.2 KB

readme.md

File metadata and controls

97 lines (72 loc) · 3.2 KB

Doc Generator

Runs analysis on instrumentation modules in order to generate documentation.

How to use

Run the doc generator:

./gradlew :instrumentation-docs:generateDocs

Instrumentation Hierarchy

An "InstrumentationEntity" represents a module that that targets specific code in a framework/library/technology. Each instrumentation uses muzzle to determine which versions of the target code it supports.

Using these structures as examples:

├── instrumentation
│   ├── clickhouse-client-05
│   ├── jaxrs
│   │   ├── jaxrs-1.0
│   │   ├── jaxrs-2.0
│   ├── spring
│   │   ├── spring-cloud-gateway
│   │   │   ├── spring-cloud-gateway-2.0
│   │   │   ├── spring-cloud-gateway-2.2
│   │   │   └── spring-cloud-gateway-common
  • Name
    • Ex: clickhouse-client-05, jaxrs-1.0, spring-cloud-gateway-2.0
  • Namespace - direct parent. if none, use name and strip version
    • clickhouse-client, jaxrs, spring-cloud-gateway
  • Group - top most parent
    • clickhouse-client, jaxrs, spring

This information is also referenced in InstrumentationModule code for each module:

public class SpringWebInstrumentationModule extends InstrumentationModule
    implements ExperimentalInstrumentationModule {
  public SpringWebInstrumentationModule() {
    super("spring-web", "spring-web-3.1");
  }

Instrumentation metadata

  • name
    • Identifier for instrumentation module, used to enable/disable
    • Configured in InstrumentationModule code for each module
  • srcPath
    • Path to the source code of the instrumentation module
  • minimumJavaVersion
    • Minimum Java version required by the instrumentation module. If not specified, it is assumed to be Java 8
  • description
    • Short description of what the instrumentation does
  • target_versions
    • List of supported versions by the module, broken down by library or javaagent support
  • scope
    • Name: The scope name of the instrumentation, io.opentelemetry.{instrumentation name}

Methodology

metadata.yaml file

Within each instrumentation source directory, a metadata.yaml file can be created to provide additional information about the instrumentation module.

As of now, the following fields are supported:

description: "Description of what the instrumentation does."

# used to mark modules that do not instrument traditional libraries (e.g. methods, annotations)
# defaults to true
isLibraryInstrumentation: false

Gradle File Derived Information

We parse gradle files in order to determine several pieces of metadata:

  • Javaagent versions are determined by the muzzle plugin configurations
  • Library versions are determined by the library dependency versions
    • when available, latestDepTestLibrary is used to determine the latest supported version
  • Minimum Java version is determined by the otelJava configurations

Scope

For now, the scope name is the only value that is implemented in our instrumentations. The scope name is determined by the instrumentation module name: io.opentelemetry.{instrumentation name}

We will implement gatherers for the schemaUrl and scope attributes when instrumentations start implementing them.