Agent

The Bearer agent helps you monitor HTTP requests on your application.

Introduction

The Bearer agent monitors the HTTP requests performed on your application. Installing it is as easy as adding a new dependency in your application. The agent does not redirect your traffic, neither introduces any network latency.

Once your application is using the Bearer agent, HTTP requests performed on your application are logged to the Bearer platform and available on your Bearer dashboard. This helps you monitor all your API usage in a few lines of code.

The agent has been built around three core concepts:

  • Scability. The Bearer agent is able to ingest and log tens of thousands of HTTP requests per second.

  • Lightweight. Using mostly asynchronous methods, the agent does not impact the performance of your application.

  • Code-isolation. If, for very unexpected reasons, the agent fails, it will fail silently without impacting your application.

Getting Started

Installing the Bearer agent generally takes less than a minute. All you need is an account on Bearer.sh to fetch your secret key and follow the procedure details below.

Node.js
Ruby
Rails

Open a terminal and install the @bearer/node-agent module into your project:

npm install --save @bearer/node-agent

Now, open your application main script (e.g. index.js or main.js) and require the Bearer agent at the top:

require('@bearer/node-agent')

We strongly recommend to require the Bearer agent first. This ensure that all external HTTP requests performed on your application are monitored.

Fetch your Bearer Secret Key by going to the Dashboard > Settings > Keys. It is a string prefixed with sk_.

Back to a terminal, from your application root directory, set up the Bearer agent with your Secret Key:

export BEARER_SECRET_KEY="YOUR_BEARER_SECRET_KEY"

Now, you can start your application (e.g. node index.js). All API calls will be monitored and available on your Bearer dashboard.

Add bearer-agent to your Gemfile:

gem 'bearer-agent'

Fetch your Bearer Secret Key by going the Dashboard > Settings > Keys. It is a string prefixed with sk_.

Back to a terminal, use the following commands from your application root directory:

# Install the Bearer gem from your application directory
bundle install
# Set the Bearer Secret Key
export BEARER_SECRET_KEY="YOUR_BEARER_SECRET_KEY"

Now, you can start your application. All API calls will be monitored and available on your Bearer dashboard.

Add bearer-agent to your Gemfile:

gem 'bearer-agent'

Fetch your Bearer Secret Key by going the Dashboard > Settings > Keys. It is a string prefixed with sk_.

Back to a terminal, use the following commands from your application root directory:

# Install the Bearer gem from your application directory
bundle install
# Set the Bearer Secret Key
export BEARER_SECRET_KEY="YOUR_BEARER_SECRET_KEY"

Now, you can start your application. All API calls will be monitored and available on your Bearer dashboard.

In rails you can update the bearer agent programaticaly using initializer file:

BearerAgent.init_config do |config|
config.disabled = false # Optional, boolean: enable/disable Bearer tracking globally
config.ignored = [] # Optional, string[]: ignore requests to specific domains
config.log_level = :ALL # Optional, "ALL" | "RESTRICTED": defaults to "ALL" set the level of information you want the agent to gather
config.filtered = [] # Optional, string[]: list of header names you want to be filtered
end

Configuration

The agent can be configured with the following environment variables:

Environment variable name

Role

BEARER_SECRET_KEY

Your Bearer Secret Key (required)

BEARER_AGENT_DISABLED

When set, the Bearer agent is disabled (whatever the value is)

BEARER_AGENT_IGNORE

Comma separated list of domains you do not want to be monitored by the agent

BEARER_AGENT_FILTERED

Comma separated list of header names you want to filter

BEARER_AGENT_LOG_LEVEL

Set the level of information you want the agent to gather. Valid values are ALL (to send full request and response) or RESTRICTED (to send only the path and query string).

Communication with Bearer

The Bearer agent communicates with Bearer servers through HTTPS. Thus, the agent requires your firewall to allow outgoing connections to agent.bearer.sh with port 443 (HTTPS).

Logs are sent in batch, using asynchronous requests.

By default, the agent sends to Bearer the full payload of each HTTP request (including both the request and the response). By default and for your own security, the Authorization header is filtered and will not be shared with Bearer. But the agent proposes more options to reduce the amount of sensitive information sent to Bearer, including:

  • BEARER_AGENT_IGNORE to ignore some domains (e.g. ["example.com", "secure.app"]);

  • BEARER_AGENT_FILTERED to flag request's headers;

  • BEARER_AGENT_LOG_LEVEL to only log the path and query string of the requests.

What if Bearer is experiencing a downtime? The Bearer agent has been built with resiliency in mind. If, for any reason, Bearer servers are experiencing unexpected latency, this will not affect your application.

On Bearer platform, logs are ingested batch by batch. On average, it takes up to 10 seconds for a log to be processed and displayed on your Bearer dashboard.

Compatibility

The Bearer agent is compatible with the following stack:

  • Node.js 8.0+

  • Ruby 2.4+