Skip to main content
This documentation explains how to configure AppSignal for Ruby to use the AppSignal Collector to send data to AppSignal. This documentation assumes that you have already followed the installation instructions. Collector mode for Ruby is in beta. Distributed tracing is a beta AppSignal Labs feature, only available when using the AppSignal hosted collector.

​
Requirements

Collector mode requires Ruby 3.1 or newer. On older Ruby versions the collector_endpoint option is ignored. Collector mode does not support JRuby. It depends on how Ruby handles forking, which JRuby does something different with.

​
Installing the OpenTelemetry gems

Collector mode sends data using OpenTelemetry. The appsignal gem does not install the OpenTelemetry gems, so add appsignal-opentelemetry next to the gem "appsignal" line already in your Gemfile:
Then run bundle install. The appsignal-opentelemetry gem does nothing on its own. It only installs the OpenTelemetry gem versions that collector mode supports, so you do not have to track them yourself. Its version matches the appsignal gem, so appsignal-opentelemetry 5.0.0 pairs with appsignal 5.0.0. If those gems are missing or their versions are unsupported, AppSignal logs a warning at startup and does not enter collector mode.

​
Deploying a collector

You can have AppSignal host a collector for you using the “Hosted Collector” page in your organization’s settings.

​
Configuring the collector

Set the collector_endpoint configuration option to the address of your collector. When using a hosted collector, this address can be found under “Collector URL” in the “Hosted Collector” settings page. Set the service_name option as well. The service name option should be set to different values for each of your services and applications (for example, “web-server”, “background-worker”) in order to tell each of them apart in distributed traces.
AppSignal for Ruby now sends its traces, metrics, and logs to the configured collector. AppSignal builds its traces out of OpenTelemetry spans when it reports to a collector. Read AppSignal for Ruby and OpenTelemetry for how to describe those spans yourself, and how AppSignal works together with instrumentation you write with the OpenTelemetry SDK.

​
Migrating to collector mode

Most configuration options have the same behavior in agent mode and collector mode. In collector mode, some data that was sent in agent mode as a single kind of data is split between multiple data types. Some configuration options that controlled whether that data was sent and how it was filtered have changed: When the collector mode options are not set, the agent mode option is used to derive a value for it, so an application that configured these config options for agent mode will still report the same data in collector mode. You can set the collector mode options to report each kind of data differently, such as filtering a background job’s arguments but not a request’s payload. AppSignal logs which values to set to keep reporting the same data, and appsignal diagnose shows them as loaded from derived:
Diagnose output

​
Request headers

request_headers lists Rack environment keys, and only some of those keys hold a request header. Collector mode reports the two separately, each under the names its own kind of value goes by:
  • keep_request_headers lists request headers, lowercase and dash-separated, as OpenTelemetry names them. HTTP_ACCEPT becomes accept.
  • keep_request_environment lists the rest, as Rack names them. QUERY_STRING stays QUERY_STRING.
The trace view shows the first in its Request headers panel and the second in its Environment panel.

​
Parameters

Collector mode reports three kinds of parameters, each with its own filter and send option:
  • The request payload: an incoming HTTP request’s parameters, such as a form body.
  • The function parameters: the arguments a background job was given.
  • The request query parameters: an incoming HTTP request’s parsed query string.
Read request parameters for more information on how to report parameters.