OpenTelemetry Ruby SDK¶

This document uses the SDK instrumentation approach: you initialize the OpenTelemetry Ruby SDK in application code and enable framework instrumentation libraries to collect calls to Rails, Rack, Sinatra, supported HTTP clients, databases, and other components. Framework instrumentation libraries can create Spans automatically, but the SDK must be explicitly configured. Installing the gems or setting environment variables alone does not automatically enable data collection.

As stated in the official Ruby documentation, Trace is stable while Metric and Log are still under development. This document only configures Trace, which is sent to DataKit over OTLP/HTTP + Protobuf and then reported by DataKit to Guance.

Ruby + OpenTelemetry Ruby SDK -> OTLP/HTTP -> DataKit -> Guance

Prerequisites¶

• CRuby 3.1 or later and Bundler. For version constraints of specific gems and frameworks, refer to their release notes and Gemfile.lock.
• A Ruby application that runs normally. Rails is used as an example below.
• Install DataKit and configure the data reporting endpoint and Token using the installation command for the target workspace.
• The application must be able to access DataKit HTTP port 9529. This document does not cover Kubernetes.

1. Enable the OpenTelemetry Collector¶

Enter the DataKit configuration directory. Copy the sample only if opentelemetry.conf does not exist; if a configuration already exists, make the adjustments in the original file:

cd /usr/local/datakit/conf.d/opentelemetry
sudo cp -n opentelemetry.conf.sample opentelemetry.conf

Verify that opentelemetry.conf contains the following configuration. customer_tags is used to preserve custom resource tags:

[[inputs.opentelemetry]]
  customer_tags = ["team"]

  [inputs.opentelemetry.http]
    http_status_ok = 200
    trace_api = "/otel/v1/traces"
    metric_api = "/otel/v1/metrics"
    logs_api = "/otel/v1/logs"

When the application and DataKit run on the same host, use 127.0.0.1:9529. In separate deployments, change [http_api].listen in the DataKit main configuration datakit.conf to a listen address accessible from the application, and configure network access control. The HTTP listen address is not configured in opentelemetry.conf.

Restart and verify DataKit:

sudo datakit service restart
curl http://127.0.0.1:9529/v1/ping

/v1/ping only verifies that the DataKit HTTP service is reachable; it does not prove that traces have been stored. For full configuration, see OpenTelemetry collector and DataKit main configuration.

2. Integrate OpenTelemetry into the Application¶

Install Dependencies¶

Run this in the application root directory. The dependencies will be written to Gemfile. Commit and deploy the updated Gemfile and Gemfile.lock to ensure these gems are installed in production as well:

bundle add opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-instrumentation-all

Initialize the SDK and Framework Instrumentation¶

Create config/initializers/opentelemetry.rb:

require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'
require 'opentelemetry/instrumentation/all'

OpenTelemetry::SDK.configure do |c|
  c.use_all
end

c.use_all enables all installed instrumentation libraries that are compatible with the application dependencies. The example sets the service name through an environment variable, so there is no need to set c.service_name separately. If you already have SDK initialization logic, merge it into the same place to avoid duplicate initialization.

Non-Rails applications should load this configuration as early as possible during startup and follow the load order of the corresponding framework instrumentation libraries. opentelemetry-instrumentation-all does not automatically create Spans for unsupported libraries or arbitrary business methods. See Ruby instrumentation libraries for the supported scope.

Configure and Start the Application¶

Set the following environment variables in the same terminal in which you start the application. In cross-host deployments, replace 127.0.0.1 with the DataKit address reachable from the application:

export OTEL_SERVICE_NAME="order-service"
export OTEL_RESOURCE_ATTRIBUTES="deployment.environment.name=prod,service.version=1.0.0,team=backend"
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://127.0.0.1:9529/otel/v1/traces"
export OTEL_PROPAGATORS="tracecontext,baggage"
export OTEL_TRACES_SAMPLER="parentbased_always_on"

bundle exec rails server -b 127.0.0.1 -p 3000

The example uses the Rails development server to verify the integration. In production, configure the environment variables in systemd, a process manager, or your deployment configuration, and restart all application processes. Do not set them only in an interactive terminal.

The opentelemetry-exporter-otlp used in this document is an HTTP/Protobuf exporter, so you cannot switch it to gRPC by changing the protocol to grpc and using port 4317.

3. Reporting Parameters¶

For production, you can switch to ratio sampling:

export OTEL_TRACES_SAMPLER="parentbased_traceidratio"
export OTEL_TRACES_SAMPLER_ARG="0.1"

0.1 means approximately 10% of root traces are sampled, while child Spans still follow the parent sampling decision. The environment variables must take effect before the SDK is initialized.

This document does not install or configure Log or Metric export pipelines, and it does not guarantee that setting signal switches for other languages will enable them. Application logs can be collected separately using DataKit log file collection. To correlate logs with traces, write the current Span's Trace ID into the logs and parse it into trace_id with a Pipeline.

Verification and Troubleshooting¶

1. Access a real business endpoint in the application to trigger supported web, HTTP, or database calls. Merely starting the process may not generate Spans.
2. After the batch export completes, query traces by service name order-service in Guance Application Performance Monitoring (APM).
3. If there is no data, first restart the application with OTEL_TRACES_EXPORTER=console and make the request again. If Spans are printed, instrumentation is working; after troubleshooting, restore the value to otlp.
4. If Spans are generated but reporting fails, check whether the DataKit collector is enabled, whether the HTTP address contains /otel/v1/traces, whether the application process inherits the environment variables, and review the error logs of the application and DataKit.
5. Short-lived scripts should call OpenTelemetry.tracer_provider.shutdown before exiting so that buffered data is exported. Forcefully terminating the process may lose Spans that have not yet been sent.

References¶

• OpenTelemetry Ruby
• Ruby Getting Started
• Ruby Instrumentation Libraries
• Ruby Exporters