Customizing Ruby Agent - Atatus Docs

This page describes the available configurations for the Atatus Ruby Agent.

Configurations

You can set following configurations in the Ruby agent.

Option	Description	Type
license_key	APM License Key of your account.	`string`
app_name	Name of your ruby project/app.	`string`
service_version	Application version to identify release of your app.	`string`
analytics	Flag to enable/disable app analytics.	`boolean`
environment	Environments allow you to easily filter data on your APM app.	`string`
capture_body	Capture request body in traces.	`string`
hostname	Default hostname is machine name. You can override it by this option..	`string`
log_path	Path of the agent log file. Set it to `-` to write logs to standard output.	`string`
enabled	enable/disable the agent.	`boolean`
notify_host	Notify URL of your on-premise Atatus server. Environment variable: `ATATUS_NOTIFY_HOST`. Example: `YOUR_ON_PREMISE_URL`.	`string`
analytics_notify_host	Analytics notify URL of your on-premise Atatus server. Environment variable: `ATATUS_ANALYTICS_NOTIFY_HOST`. Example: `YOUR_ON_PREMISE_URL`.	`string`

In Rails Create a file config/atatus.yml and set your configuration in Rails.

license_key: "lic_apm_xxxxxxx"

app_name: "Ruby App"
notify_host: "YOUR_ON_PREMISE_URL"
analytics_notify_host: "YOUR_ON_PREMISE_URL"

service_version: "1.2.0"

analytics: true

environment: "production"

capture_body: "all"

hostname: "web1.example.com"

log_path: "/var/log/atatus/atatus-ruby-agent.log"

enabled: true

In Sinatra Set your configuration to config.ru file.

Atatus.start(
    license_key: "lic_apm_6e49699e38c8498f9a29a05b1adc0182",

    app_name: "Ruby App",
    notify_host: "YOUR_ON_PREMISE_URL",
    analytics_notify_host: "YOUR_ON_PREMISE_URL",

    service_version: "1.2.0",

    analytics: true,

    environment: "production",

    capture_body: "all",

    hostname: "web1.example.com",

    log_path: "/var/log/atatus/atatus-ruby-agent.log",

    enabled: true
)

Set app version

If you use an version to identify releases of your app, you can send it to Atatus. It is highly recommended to set service_version. In Rails Create a file config/atatus.yml and set your configuration in Rails.

# In config/atatus.yml
license_key: "lic_apm_xxxxxxx"
app_name: "Ruby App"

service_version: "1.2.0"

# In Environment
export ATATUS_SERVICE_VERSION=1.2.0

In Sinatra Set your configuration to config.ru file.

# In config.ru
Atatus.start(
    license_key: "lic_apm_6e49699e38c8498f9a29a05b1adc0182",
    app_name: "Ruby App",

    service_version: "1.2.0"
)

# In Environment
export ATATUS_SERVICE_VERSION="1.2.0"

Set analytics

App Analytics collects all requests individually with contextual data. In Rails Create a file config/atatus.yml and set your configuration in Rails.

# In config/atatus.yml
license_key: "lic_apm_xxxxxxx"
app_name: "Ruby App"

analytics: true

In Sinatra Set your configuration to config.ru file.

# In config.ru
Atatus.start(
    license_key: "lic_apm_6e49699e38c8498f9a29a05b1adc0182",
    app_name: "Ruby App",

    analytics: true
)

Set environment

If you are tracking multiple environments with a single APM project, then you can set a environment as follows. In Rails Create a file config/atatus.yml and set your configuration in Rails.

# In config/atatus.yml
license_key: "lic_apm_xxxxxxx"
app_name: "Ruby App"

environment: "production"

# In Environment
export ATATUS_ENVIRONMENT="production"

In Sinatra Set your configuration to config.ru file.

# In config.ru
Atatus.start(
    license_key: "lic_apm_6e49699e38c8498f9a29a05b1adc0182",
    app_name: "Ruby App",

    environment: "production",
)

# In Environment
export ATATUS_ENVIRONMENT="production"

Enable Capture Body

This capture body option is disabled by default. If you want to see the request body in traces, you can enable this option in startup options. The body will be captured only in follwing content-types: application/x-www-form-urlencoded, text/*, application/json, application/xml. In Rails Create a file config/atatus.yml and set your configuration in Rails.

# In config/atatus.yml
license_key: "lic_apm_xxxxxxx"
app_name: "Ruby App"

capture_body: "all"

# In Environment
export ATATUS_CAPTURE_BODY="all"

In Sinatra Set your configuration to config.ru file.

# In config.ru
Atatus.start(
    license_key: "lic_apm_6e49699e38c8498f9a29a05b1adc0182",
    app_name: "Ruby App",

    capture_body: "all",
)

# In Environment
export ATATUS_CAPTURE_BODY="all"

Configure a custom host name

By default, we will fetch the host name using Ruby, but you can override this as follows: In Rails Create a file config/atatus.yml and set your configuration in Rails.

# In config/atatus.yml
license_key: "lic_apm_xxxxxxx"
app_name: "Ruby App"

hostname: "web1.example.com"

# In Environment
export ATATUS_HOSTNAME="web1.example.com"

In Sinatra Set your configuration to config.ru file.

# In config.ru
Atatus.start(
    license_key: "lic_apm_6e49699e38c8498f9a29a05b1adc0182",
    app_name: "Ruby App",

    hostname: "web1.example.com",
)

# In Environment
export ATATUS_HOSTNAME="web1.example.com"

Disable agent

Using this option, you can completely disable the agent, including instrumentation and remote config polling. You can set enabled option to false to disable agent. In Rails Create a file config/atatus.yml and set your configuration in Rails.

# In config/atatus.yml
license_key: "lic_apm_xxxxxxx"
app_name: "Ruby App"

enabled: false

# In Environment
export ATATUS_ENABLED=false

In Sinatra Set your configuration to config.ru file.

# In config.ru
Atatus.start(
    license_key: "lic_apm_6e49699e38c8498f9a29a05b1adc0182",
    app_name: "Ruby App",

    enabled: false,
)

# In Environment
export ATATUS_ENABLED=false

Set log path

By default, the agent does not write its logs to a file. To turn on agent logs, set log_path to the full path of a log file, or set it to - to write logs to standard output. In Rails Add log_path to config/atatus.yml:

license_key: "lic_apm_xxxxxxx"
app_name: "Ruby App"

log_path: "/var/log/atatus/atatus-ruby-agent.log"

In Sinatra Pass log_path to Atatus.start in config.ru:

Atatus.start(
    license_key: "lic_apm_xxxxxxx",
    app_name: "Ruby App",

    log_path: "/var/log/atatus/atatus-ruby-agent.log"
)

In either framework, you can set it with an environment variable instead:

$ export ATATUS_LOG_PATH="/var/log/atatus/atatus-ruby-agent.log"

Use an absolute path for log_path. A relative path is resolved from the folder your application process starts in, which may not be your project folder. Make sure the user running your application can write to the log file’s folder.