How we configured OpenTelemetry logs in Rails

Sep 01, 2026 04:12 AM - 1 hour ago 1

Recently, we needed to adhd observability to a Rails task without getting locked into a azygous vendor. OpenTelemetry was the earthy choice.

It generates 3 kinds of telemetry data, called signals: logs, metrics, and traces. Each awesome is independent, truthful you tin adopt 1 without the others.

All of these signals recreation successful a standard, vendor-agnostic format known arsenic OTLP (OpenTelemetry Protocol). Because this format is modular crossed the industry, we tin move backends (like Datadog, New Relic, aliases Grafana Cloud) successful the future without rewriting immoderate exertion code.

In this post, we will explicate really we configured the OpenTelemetry Ruby SDK to export logs straight to our vendor, Grafana Cloud. We will besides talk a few issues we encountered on the measurement and the upstream fixes we contributed.

Exporting straight to the vendor

The modular OpenTelemetry deployment involves moving an OpenTelemetry Collector alongside your application. The Collector is simply a abstracted process, usually a sidecar instrumentality aliases a work connected the aforesaid host. Your application sends telemetry to it complete the section network, and the Collector past batches that information and forwards it to the vendor.

To support our infrastructure simple, we bypassed the Collector and exported logs directly from the Ruby SDK to Grafana Cloud. The Scout APM logging gem uses a akin attack and sends logs straight from the app.

Our log measurement is small, truthful the SDK's built-in batching is enough. A Collector is still the amended prime if you request buffering, sampling, aliases scrubbing outside the app.

Setting up the Ruby SDK for logs

Add the pursuing gems to your Gemfile:

gem "opentelemetry-sdk" gem "opentelemetry-logs-sdk" gem "opentelemetry-exporter-otlp" gem "opentelemetry-exporter-otlp-logs" gem "opentelemetry-instrumentation-all" gem "opentelemetry-instrumentation-logger"

OpenTelemetry is highly modular, truthful each gem handles a circumstantial responsibility:

opentelemetry-sdk: The halfway OpenTelemetry model (traces and the configuration introduction point).
opentelemetry-logs-sdk: Adds support for the logging awesome (which is separate from traces).
opentelemetry-exporter-otlp: Exports traces complete the web via OTLP.
opentelemetry-exporter-otlp-logs: Exports logs complete the web via OTLP.
opentelemetry-instrumentation-all: Bundles the instrumentation gems, including Rails, Rack, and Active Record.
opentelemetry-instrumentation-logger: Hooks into the modular Ruby Logger so log messages go OpenTelemetry log records.

With these gems installed, the exporter needs to cognize wherever to nonstop the data. Set your vendor's endpoint and authentication token arsenic situation variables (the SDK automatically detects standard OTLP exporter situation variables):

OTEL_EXPORTER_OTLP_ENDPOINT="https://your-vendor.com/otlp" OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic <your-token>"

Finally, we request to initialize the SDK truthful it starts collecting and exporting data. Create an initializer (config/initializers/opentelemetry.rb):

return if ENV["OTEL_EXPORTER_OTLP_ENDPOINT"].blank? OpenTelemetry::SDK.configure do |c| c.service_name = "our-rails-app" c.use_all end

Here, c.use_all enables each instrumentation that has been required, which means the ones bundled successful opentelemetry-instrumentation-all plus opentelemetry-instrumentation-logger.

Testing it locally

Now that the SDK is configured, you tin trial it by setting OTEL_LOGS_EXPORTER=console. This prints log records successful your terminal instead of sending them to the vendor, which is the quickest measurement to corroborate your setup works earlier deploying.

Issues we recovered and fixed successful the Ruby SDK

When we exported logs to Grafana Cloud, we recovered 2 issues wherever the Ruby SDK behaved otherwise than different connection SDKs and the OpenTelemetry specification.

1. Exporter dropped the guidelines path

Some vendor backends require sending OTLP information to an endpoint pinch a specific base path, specified arsenic /otlp successful our lawsuit pinch Grafana Cloud, but the exporter dropped it while appending the awesome path.

Endpoint: https://your-vendor.com/otlp Expected: https://your-vendor.com/otlp/v1/logs Actual: https://your-vendor.com/v1/logs

We reported this in issue #2157 and fixed it in PR #2158, which was released successful opentelemetry-exporter-otlp-logs v0.5.1.

2. Handling HTTP 204 responses

Grafana Cloud returns 204 No Content aft ingesting logs, but the exporter only treated 200 OK arsenic success. The exports really succeeded, but our app logged each 1 arsenic a failure.

We raised issue #2043 and fixed it in PR #2044, which was released successful opentelemetry-exporter-otlp-logs v0.4.0.

Next steps: system logging

Now that logs are being successfully exported, the adjacent logical measurement is structured logging. That's excessively overmuch to screen here, but the rails_semantic_logger gem is simply a awesome spot to start, and we mightiness moreover screen the afloat OpenTelemetry setup for it successful a early post!