DOCSEARCHbyAlgolia
Submit Docs

OpenTelemetry Ruby

repository·main·Indexed 20 days ago

https://github.com/open-telemetry/opentelemetry-ruby

The official Ruby client implementation for OpenTelemetry, providing APIs and SDKs for collecting traces, metrics, and logs. It includes the opentelemetry-api gem for core interfaces and the opentelemetry-common gem for helpers like Net::HTTP context propagation. The project provides tools for performance benchmarking and reference applications, such as the Dice Roller, to demonstrate OTLP exporter configuration and instrumentation.

Tokens
54.2K
Snippets
176
Records
238
Agent score
68%

What's inside opentelemetry-ruby

  1. Overview of opentelemetry-exporter-otlp-common

    main
    The opentelemetry-exporter-otlp-common gem provides a shared set of utilities used by various OTLP (OpenTelemetry Protocol) exporters within the OpenTelemetry Ruby ecosystem. It is not intended to be used directly by end-users for exporting data, but rather serves as a foundational component for specific OTLP exporters like opentelemetry-exporter-otlp-grpc or opentelemetry-exporter-otlp-http.

  2. What is opentelemetry-propagator-jaeger?

    main

    The opentelemetry-propagator-jaeger gem provides a propagator for the Jaeger native propagation format.

    This allows your application to participate in distributed tracing by propagating context using Jaeger's specific format. It can be used independently or alongside propagators for other formats to support multiple context propagation scenarios. It is compatible with any OpenTelemetry SDK implementation, including the official opentelemetry-sdk gem.

  3. Understand the Experimental SDK

    main

    The Experimental SDK in OpenTelemetry Ruby contains bleeding-edge functionality. Users should be aware that the APIs within this SDK may be unstable and subject to change without notice.

    Currently, the experimental SDK includes:

    • traceresponse propagator: Based on the W3C trace-context editor's draft.
    • Consistent Probability Sampler: An implementation marked as experimental in the OpenTelemetry specification.

  4. Configure metrics using Views

    main

    Views allow you to customize how metrics are collected and exported. You can use them to:

    • Change aggregation: Apply specific aggregation logic (like ExponentialBucketHistogram) to instruments matching a name pattern.
    • Drop instruments: Suppress noisy or low-value instrumentation by using OpenTelemetry::SDK::Metrics::Aggregation::Drop.
    • Restrict attribute keys: Use an allowlist to keep only specific attribute keys and drop all others.

    add_view supports wildcard matching (* and ?) for instrument names.

    # Change aggregation for a specific instrument using wildcards
OpenTelemetry.meter_provider.add_view(
  '*exponential*',
  aggregation: OpenTelemetry::SDK::Metrics::Aggregation::ExponentialBucketHistogram.new(
    aggregation_temporality: :cumulative,
    max_scale: 20
  ),
  type: :histogram,
  unit: 'ms'
)

# Drop all metrics from a specific meter
OpenTelemetry.meter_provider.add_view(
  '*',
  aggregation: OpenTelemetry::SDK::Metrics::Aggregation::Drop.new,
  meter_name: 'noisy_library'
)

# Restrict which attribute keys are retained
OpenTelemetry.meter_provider.add_view(
  'http.request.duration',
  attribute_keys: { 'http.method' => nil, 'http.status_code' => nil }
)

  6. How opentelemetry-api fits into your project

    main

    The opentelemetry-api gem defines core OpenTelemetry interfaces using abstract classes and no-op implementations. It allows you to code against standard interfaces to produce telemetry data (like traces and metrics) without being tied to a specific collection or export mechanism.

    Key distinction for developers:

    • Libraries: Should depend only on opentelemetry-api. This allows the library to produce telemetry while deferring the choice of a concrete implementation (like an SDK) to the application developer.
    • Applications: Must also install a concrete implementation, such as the opentelemetry-sdk gem, to actually collect, analyze, and export the telemetry data produced by the API.

  7. Relationship between opentelemetry-api and opentelemetry-sdk

    main

    Understanding which gem to use depends on whether you are building an application or a library:

    • Applications: Should install opentelemetry-sdk. The SDK provides the actual functionality to collect, analyze, and export telemetry data (traces, metrics, etc.).
    • Libraries: Should depend only on opentelemetry-api. Libraries should produce telemetry using the API interfaces but should not dictate how that data is handled or exported. This allows the application developer to choose the concrete implementation (the SDK) at runtime.

  8. How the OpenTelemetry Registry works

    main

    The Instrumentation Registry acts as a decoupling layer between instrumentation libraries and the OpenTelemetry SDK.

    • Decoupling: It allows instrumentation to avoid direct dependencies on a specific SDK implementation.
    • Hierarchy: The SDK depends on the Registry, the instrumentation Base class depends on the Registry, and auto-instrumentation libraries extend that Base class.
    • Interoperability: Because instrumentation depends on the Registry rather than a specific SDK, any implementation of an OpenTelemetry API-compatible SDK can utilize community-made instrumentation.

  9. How opentelemetry-metrics-api works with SDKs

    main

    The opentelemetry-metrics-api gem defines core OpenTelemetry interfaces using abstract classes and no-op implementations.

    • Libraries should depend only on opentelemetry-metrics-api. This allows the library to produce telemetry data without forcing a specific collection or export method on the user.
    • Applications must install a concrete implementation, such as opentelemetry-metrics-sdk, to actually collect, analyze, and export the metric data produced by the API.

  10. Quickstart: Basic Metrics Configuration and Recording

    main

    This example demonstrates how to manually configure the SDK, set up a console exporter, create a meter, and record a measurement using a histogram. Note that ENV['OTEL_METRICS_EXPORTER'] = 'none' is used to disable automatic exporter configuration so you can set one manually.

    require 'opentelemetry/sdk'
require 'opentelemetry-metrics-sdk'

# Disable automatic exporter configuration so we can set one manually.
ENV['OTEL_METRICS_EXPORTER'] = 'none'

OpenTelemetry::SDK.configure

# Create an exporter and register it with the meter provider.
console_exporter = OpenTelemetry::SDK::Metrics::Export::ConsoleMetricPullExporter.new
OpenTelemetry.meter_provider.add_metric_reader(console_exporter)

# Create a meter and instrument.
meter = OpenTelemetry.meter_provider.meter('my_app')
histogram = meter.create_histogram('http.request.duration', unit: 'ms', description: 'HTTP request duration')

# Record a measurement.
histogram.record(200, attributes: { 'http.method' => 'GET', 'http.status_code' => '200' })

# Flush metrics to the exporter.
OpenTelemetry.meter_provider.metric_readers.each(&:pull)

OpenTelemetry.meter_provider.shutdown

  12. Install opentelemetry-exporter-otlp-logs

    main

    To use the OTLP logs exporter, you need both the SDK and the exporter gem. You can install them via gem or include them in your Gemfile using Bundler.

    Using gem:

    gem install opentelemetry-logs-sdk
gem install opentelemetry-exporter-otlp-logs

    Using Bundler: Include opentelemetry-sdk in your Gemfile.

    gem install opentelemetry-logs-sdk
gem install opentelemetry-exporter-otlp-logs