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:

  • Scalability. 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 only takes a few minutes. All you need is an account on Bearer.sh. Take a look at our guide below to get started.

Configuration

Node.js
Ruby
Node.js

You can update your configuration when you initialize the Agent in your app.

Below you can find configuration options that we currently support:

Bearer.init({
"logLevel": "RESTRICTED",
"disabled": false,
"secretKey": "your secret key",
"ignored": ["domain.com", "example.com"],
"stripSensitiveData": true,
"stripSensitiveKeys": ["^authorization$"],
"stripSensitiveRegex: "we have to keep it secret$"
})
Ruby

You can update your configuration when you initialize the Agent in your app.

Below you can find configuration options that we currently support:

Bearer.init_config do |config|
config.secret_key = "YOUR_BEARER_SECRET_KEY" # Required, string: Your Bearer private key
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.strip_sensitive_data = true # Optional, boolean: Remove sensitive data before sending it to bearer.sh
config.strip_sensitive_keys = [/^authorization$/i, /^client.id$/i, /^access.token$/i, /^client.secret$/i] # Optional, Regexp[]: list of keys to strip.
config.strip_sensitive_regex = %r{[a-zA-Z0-9.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*} # Optional, Regexp: Regular expression used for value stripping.
end

For full configuration options, such as setting up environment variables or using a config file, check out the configuration page:

Keeping your data protected

Node.js
Ruby
Node.js

To keep your application safe and prevent sensitive data leaks, we recommend that you sanitize your data before sending it to Bearer. The best way to do it is to use a bearer.json file to setup the sanitization level that best suits your needs:

The default values are set as follows:

Bearer.init({
"stripSensitiveData": true,
"stripSensitiveKeys": ["^authorization$", "^client.id$", "^access.token$", "^client.secret$"],
"stripSensitiveRegex": "[a-zA-Z0-9.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*"
})

That default configuration prevents most of your API credentials from being sent to Bearer.

Sanitization options explained

  • stripSensitiveData - Globally enable/disable data sanitization. It's enabled by default. If you set it to false no sanitization will take place, and all the data will be sent to Bearer unfiltered.

  • stripsSensitiveKeys - List of key names regex patterns that will be applied to sanitize values in headers, query parameters, or the response body. If you specify "stripSensitiveKeys": "^authorization$" the following sanitization actions would take place:

    • In headers: the value of the "authorization" header will be sanitized and be sent to Bearer as authorization: [FILTERED]

    • In query string parameters: the value of the "authorization" query parameter will be sanitized. In the Bearer dashboard your URL will look like: http://www.example.com/endpoint?authorization=[FILTERED]

    • In the response body: any value of "authorization" key in response payload will be replaced with [FILTERED] (e.g., { "name": "John", "authorization": "granted" } will be sent to the Bearer dashboard as { "name": "John", "authorization": "[FILTERED]" }. This rule only applies to responses with a Content-Type header set to application/json.

  • stripSensitiveRegex - A regular expression that will be used to sanitize any value in headers, query string parameters, or the response body. Bearer will check all the values sent in the request or response and will replace matching patterns with [FILTERED].

Ruby

We recommend you sanitize your data before sending it to the Bearer dashboard. We think it is the best to use an initializer file to setup the sanitization level that best suits your needs:

The default values are set as follows:

Bearer.init_config do |config|
config.strip_sensitive_data = true
config.strip_sensitive_keys = [/^authorization$/i, /^client.id$/i, /^access.token$/i, /^client.secret$/i]
config.strip_sensitive_regex = %r{[a-zA-Z0-9.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*}
end

Configuration options explained

  • config.strip_sensitive_data - Globally enable/disable data sanitization. It's enabled by default. If you set it to false no sanitization will take place, and all the data will be sent to the Bearer dashboard as-is.

  • config.strips_sensitive_keys - List of key names regex patterns that will be applied to sanitize values in headers, query parameters or response body. If you specify config.strip_sensitive_keys = [/authorization/] the following sanitization actions would take place:

    • In headers: "authorization" header value will be sanitized and would be sent to the Bearer dashboard as "authorization: [FILTERED]"

    • In query string parameters: "authorization" query parameter value will be sanitized, and in the Bearer dashboard your URL will look like: "http://www.example.com/auth?authorizaiton=[FILTERED]"

    • In application/json response body: Any value of "authorization" key in response payload will be replaced with "[FILTERED]" (e.g., { "name": "John", "authorization": "granted" } will be sent to the Bearer dashboard as { "name": "John", "authorization": "[FILTERED]" }

  • config.strips_sensitive_regex - A regular expression that will be used to sanitize any value in headers, query string parameters or response body. Bearer will check all the values sent in the request or response and will replace matching patterns with "[FILTERED]".

Compatibility

The Bearer agent is compatible with the following stack:

  • Node.js 8.0+

  • Ruby 2.4+