OpenTelemetry Testing

This project provides a testing framework for OpenTelemetry instrumentation, enabling you to validate and debug your telemetry setup. It includes utilities for setting up an OpenTelemetry Collector, exporting traces, and verifying telemetry data.

Features

OpenTelemetry Integration: Provides a builder for configuring OpenTelemetry providers for metrics, traces, and logs.
Testcontainers Support: Uses testcontainers to spin up an OpenTelemetry Collector for testing.
Trace Validation: Includes utilities to parse and validate traces exported to a file.
Configurable: Easily customize the OpenTelemetry Collector configuration.

Getting Started

Prerequisites

Rust (edition 2024)
Docker (required for testcontainers)

Installation

Add this crate to your Cargo.toml:

[dependencies]
opentelemetry-testing = "0.1.0"

Usage

Setting Up OpenTelemetry

Use the OpenTelemetryBuilder to configure and install OpenTelemetry providers:

let builder = OpenTelemetryBuilder {
    otel_collector_endpoint: "http://127.0.0.1:4317".into(),
    otel_internal_level: "off".into(),
};
let provider = builder.build().unwrap();
provider.install().unwrap();

Running Tests with Testcontainers

The ObservabilityContainer struct simplifies setting up an OpenTelemetry Collector for testing:

#[tokio::test]
async fn test_traces() {
    let container = ObservabilityContainer::create().await;
    let provider = container.install().await;

    // Your test logic here

    provider.flush();
    let traces = container.json_traces();
    assert!(traces.resource_spans.len() > 0);
}

Validating Traces

You can parse and validate traces exported to a file:

let traces = container.json_traces();
let scope_span = traces.find_scope_span("my-instrumentation");
assert!(scope_span.is_some());

OpenTelemetry Collector Configuration

The OpenTelemetry Collector is configured using the otelcol-config.yml file. By default, it exports traces to a JSON file at /tmp/output/traces.json.

Example configuration:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
exporters:
  file/traces:
    path: /tmp/output/traces.json
    format: json
service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [file/traces]

Development

Running Tests

Run the tests using cargo:

cargo test

Formatting

Ensure your code is formatted:

cargo fmt

Linting

Check for common issues:

cargo clippy

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

opentelemetry-testing 0.1.0