---
title: "Ruby agent"
slug: "ruby-agent"
updated: 2024-06-13T05:12:44Z
published: 2024-05-09T15:17:34Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://traceabledocs.document360.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Ruby agent

Traceable's Ruby tracing agent is an in-app tracing agent. It collects information from your Ruby application and sends it to Traceable's platform agent. The platform agent sends the information to Traceable's SaaS platform for further analysis. The topic covers deployment, verification, troubleshooting, and uninstall information. Following is a high-level deployment diagram for Traceable's ruby agent:

![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_ruby_agent_deployment.jpg)

---

## Before you begin

Make a note of the following points before you proceed with the deployment:

- Make sure that Traceable's platform agent is already installed. For more information, see [Platform agent](/v1/docs/tpa).
- Ensure your application is built on Ruby's version 2.7.x, 3.0.x, 3.1.x, and 3.2.x
- Ruby agent uses OTLP exporter; hence, the default exporter port is 4318.
- Basic knowledge of Ruby commands. For more information, see [RubyGems basics](https://guides.rubygems.org/rubygems-basics/).

### Supported libraries

Traceable's Ruby agent supports the following libraries:

- Rails: v5.0.0+
  - ActionPack
  - ActionView
  - ActiveRecord
  - ActiveSupport
- Sinatra: v2.0.0+
- http.rb
- faraday
- rest-client
- net::http
- pg
- mysql2
- mongo

---

## Install Ruby agent

You can install Traceable's Ruby agent in one of the following two ways:

#### Option 1

Traceable's Ruby agent is available on [Rubygems.org](https://rubygems.org/). You can install it by entering the following command:

```actionscript
gem install hypertrace-agent
```

#### Option 2

You can also install Traceable's Ruby agent by adding it to your application's `Gemfile`. For example,

```ruby
source "https://rubygems.org"

gem 'hypertrace-agent'
```

Install the agent by entering the following command to install it using Bundler:

```actionscript
bundle install
```

---

## Instrument applications

The following sections provide examples of instrument Rails and Sinatra applications.

### Instrument a Rails application

To instrument a Rails application, create an initializer; for example,

```ruby
config/initializers/hypertrace.rb
```

Inside the initializer, add the following:

```ruby
require 'hypertrace'

Hypertrace::RubyAgent.instrument!
```

### Instrument a Sinatra application

Sinatra is an open-source software web application library and domain-specific language written in Ruby. To instrument a Sinatra application with Traceable's Ruby agent, add the following lines to the application's main entry point:

```ruby
require 'hypertrace'
Hypertrace::RubyAgent.instrument!
```

---

## Traceable agent configuration

You can configure the Ruby agent through a configuration file or environment variables.

#### Using configuration file

Following is a sample configuration file with default values to configure Traceable agent:

```actionscript
service_name: rubyagent
reporting:
  endpoint: http://localhost:4318/v1/traces 
  secure: false
  trace_reporter_type: OTLP
data_capture:
  http_headers:
    request: true
    response: true
  http_body:
    request: true
    response: true
  rpc_metadata:
    request: true
    response: true
  rpc_body:
    request: true
    response: true
  body_max_size_bytes: 131072
propagation_formats: ["B3"]
```

The `service_name` in the configuration file is the service name with which you identify the Ruby application in Traceable Platform. You can also use your own configuration file by setting the environment variable `HT_CONFIG_FILE` with a value of path to the file.

#### Using environment variable

You can also configure the Traceable agent using the environment variable. Add HT_ followed by the configuration field name. For example,

- `HT_SERVICE_NAME`
- `HT_REPORTING_ENDPOINT`
- `HT_REPORTING_TRACE_REPORTER_TYPE`
- `HT_DATA_CAPTURE_HTTP_HEADERS_REQUEST`
- `HT_BODY_MAX_SIZE_BYTES`
- `HT_PROPAGATION_FORMATS`

Once you have configured Traceable's Ruby agent, send traffic to the Ruby application. If the installation is successful, you will see traces in the Traceable Platform, as shown in the **Verification**section.

---

## Verification

To verify a successful installation, login to Traceable Platform and navigate to **API Catalog →** **Services**. Find the service name you configured during [Traceable agent configuration](/v1/docs/ruby#traceable-agent-configuration) and click on it. Click on the **Traces** tab to view the traces. You can click on a trace to view detailed information about the trace. For example, as shown in the screenshot below:

![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_ruby_agent_verification.png)

---

## Uninstall

You can uninstall Traceable's Ruby agent by entering the following command:

```actionscript
gem uninstall hypertrace-agent
```

After you have run the above command, remove the following line from your application's `Gemfile`:

```actionscript
gem "hypertrace-agent"
```

---

## Troubleshooting

If you do not see any data in Traceable's platform after a few minutes:

1. Make sure that the instrumented Ruby application is receiving traffic.
2. Check whether Traceable's platform agent has the correct agent token configured. You can copy the agent token by logging into your Traceable platform and navigating to **Settings**( ![](https://cdn.document360.io/24f14f07-13d1-4684-8fae-6d8f811768ee/Images/Documentation/traceable_gear_icon_Settings.png)) → **Account**→ **Agent token**.
3. Check the Traceable platform agent logs for any connectivity issues or errors. You can view the logs by navigating to `/var/traceable/log/`.
4. Check the Ruby tracing agent logs for any connectivity issues or errors. You will have to change the log level to `DEBUG` by setting,` ENV TA_LOG_LEVEL DEBUG`, and restarting the application. For example, in the case of a K8s application, you can configure this in the `dockerfile`.

If you need further assistance, reach out to [Traceable support](https://support.traceable.ai/hc/en-us).