Ruby source integration¶

Beacon Ruby is an instrumentation source project based on OpenTelemetry Ruby Contrib. Applications reference the required instrumentation gems from source and explicitly initialize the OpenTelemetry SDK to export traces using OTLP HTTP/protobuf.

Beacon Ruby retains upstream gem identities and is distributed as source archives. It does not provide a separate beacon-ruby gem, executable agent, or zero-code preload. Setting environment variables alone does not enable collection.

Requirements¶

Install a Ruby toolchain and Bundler supported by the project, with access to GitHub and RubyGems. See the source installation guide for runtime requirements.
Local trace verification requires Linux, Python, and Docker. Download the Collector image used by the validation script in advance, following the acceptance instructions in the source archive.

Download and install¶

Select a source distribution from Beacon Ruby Releases. Download the source archive, SOURCE.txt, and SHA256SUMS into the same new directory.
Verify the files in the download directory:
```
sha256sum -c SHA256SUMS
```
Extract the archive only after verification succeeds, then enter the source root directory. SOURCE.txt records the source commit and upstream baseline. The archive includes licenses; dependencies must be installed separately.

For application integration, refer to the Gemfile in the source archive. Reference opentelemetry-instrumentation-base and opentelemetry-instrumentation-net_http from the same Beacon source distribution, and use matching opentelemetry-sdk and opentelemetry-exporter-otlp dependencies. Adjust the source paths to the application's deployment location, and commit the application's Gemfile and Gemfile.lock.

Installing instrumentation gems with the same names directly from RubyGems selects upstream packages. Check the Bundler dependency sources to confirm that the application loads the selected Beacon source.

Initialize the SDK¶

Load the required libraries during application startup, then initialize the SDK and enable Net::HTTP instrumentation:

require 'bundler/setup'
require 'net/http'
require 'opentelemetry-sdk'
require 'opentelemetry-exporter-otlp'
require 'opentelemetry-instrumentation-net_http'

OpenTelemetry::SDK.configure do |config|
  config.service_name = 'my-ruby-service'
  config.use 'OpenTelemetry::Instrumentation::Net::HTTP'
end

Merge this configuration into the application's existing initialization logic to avoid initializing the SDK twice. Instrumentation libraries create spans only for calls through supported libraries; they do not automatically cover arbitrary business methods. See the Ruby example in the source archive for root spans, requests, and flushing before exit.

Verify Net::HTTP traces¶

First use the validation script included with the source to check dependencies and the instrumentation path. Run from the source root directory:

cd beacon/validation
BUNDLE_FROZEN=true bundle install
BUNDLE_FROZEN=true python3 collector_smoke.py

The script uses locked dependencies and a Collector image, starts a temporary HTTP server and local OpenTelemetry Collector, and runs an instrumented Ruby HTTP request. It checks service name beacon-ruby-import-smoke, one root span, one HTTP client span, their shared Trace ID, and the parent-child relationship. On success it prints:

Collector received the service identity and correlated root/client spans.

The script cleans up the temporary servers, container, and trace output when it finishes. This workflow verifies that synthetic requests reach the local Collector; it does not prove ingestion by a production backend.

Receivers and capability scope¶

Published acceptance records cover the shared instrumentation base, Net::HTTP semantic modes, and trace export to a local Collector over OTLP HTTP/protobuf. Rails, other integrations, DataKit, metrics, logs, profiling, and Security are outside the validated scope.

To report traces to Guance, enable the DataKit OpenTelemetry HTTP receiver using Common configuration, then configure the HTTP/protobuf export endpoint as described in OpenTelemetry Ruby SDK. SDK initialization is still required. Validate the DataKit integration separately in the actual application environment; local Collector verification does not prove DataKit ingestion.

Generate real Net::HTTP requests, then open APM > Traces in Guance and filter by the configured service name. Check traces, spans, and parent-child relationships.

Upgrades and rollback¶

Keep each source distribution in a separate directory. Retain verified archives, checksums, SOURCE.txt, the application Gemfile, lockfile, and SDK initialization configuration. Before upgrading, review the release notes and verify the instrumentation paths you need.

To roll back, restore the previous source references, dependencies, and initialization configuration, restart the application, and verify telemetry again. See the source installation guide for more details.