How to set the User Agent Header

When integrating a new language binding, collector, or third-party service with Librato we recommend setting a User Agent header on each API request that identifies your integration. A custom User Agent allows us to identify those requests made on-behalf of your integration and/or originating from your third-party service.

Setting a custom User Agent has the following benefits:

  • We can track usage statistics for each collector. This let’s us know which service integration we should focus our collaborative efforts on or where we can help improve the collector ecosystem.
  • We can better assist customers that have problems using the service by identifying which services they are using and directing them appropriately.
  • We can identify customers that are using know buggy or vulnerable service integrations and assist them in updating.

How To Set a User Agent

A custom User Agent can be sent on any request to the Librato API by setting the HTTP header “User-Agent”. For example, in curl you would set the header with the -H flag:

curl -H 'User-Agent: my-integration/1.2.3'

A Simple User Agent

The full format for a User Agent header is explained in this Wikipedia article, but a simple User Agent should follow the format:

<Integration Name>/<Version>

For example, if you were integrating the service “BrowserMetrics.io”, and the current version of your integration library is “4.5.9”, the User Agent header should look like:

BrowserMetrics.io/4.5.9

Including Additional Meta-data

A User Agent can also include additional meta-data that identifies the particular request. This data is specified as a semi-colon separated string, included in parenthesis spaced after the User Agent string.

For example, if a service could be accessed from different devices (e.g. an iPad) and from different locales, an example User Agent would be:

BrowserMetrics.io/4.5.9 (iPad; en-us)

Including Library and Language Bindings

A single User Agent header can include multiple agents separated by spaces. If a service integration is built upon an existing client library it is beneficial to include these library names and versions as well. Different client library versions may behave differently, so it is imperative to know which ones were used in the integration.

For example, the Librato librato-metrics Ruby gem uses the following User Agent that identifies the name of the HTTP client library (faraday) and its version:

librato-metrics/1.0.2 (ruby; 1.8.7p358; x86_64-linux) direct-faraday/0.8.4