AppSignal Ruby Collector Configuration

Use collector mode to send data to AppSignal through the AppSignal Collector. Distributed tracing is only supported when sending data through an AppSignal hosted collector. By the end of this page, your app will report to the collector you choose, and each service will identify itself with its own service name.

This page assumes that you have already followed the installation instructions.

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:

Gemfile

gem "appsignal"
gem "appsignal-opentelemetry"

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 your collector’s base URL. When using a hosted collector, copy the “Collector URL” from the “Hosted Collector” settings page.

Set the service_name option to identify this application in traces. Use a different value for each service, such as web-server or background-worker.

config/appsignal.rb

Appsignal.configure do |config|
  # ... other settings ...
  config.collector_endpoint = "https://collector.example"
  config.service_name = "web-server"
end

AppSignal for Ruby now sends its traces, metrics, and logs to the configured collector.

To check that AppSignal loaded these settings, run bundle exec appsignal diagnose --no-send-report and confirm that the Configuration section lists the expected collector_endpoint and service_name. Then send a request or run a job and confirm its trace appears in AppSignal.

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:

Agent mode	Collector mode
request_headers	keep_request_headers, keep_request_environment
filter_parameters	filter_request_payload, filter_function_parameters, filter_request_query_parameters
send_params	send_request_payload, send_function_parameters, send_request_query_parameters

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

keep_request_headers: ["accept"]
  Sources:
    default: ["accept", "accept-charset", "accept-encoding", "accept-language", "cache-control", "connection", "content-length", "range"]
    derived: ["accept"]

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.