HTTP

Send logs to Timber via the Timber HTTP API

Timber has a rich HTTP API that you can use to send logs to the Timber platform.

Timber offers language level libraries and support for log forwarders that handle the efficient and reliable delivery of your log data. We highly recommend using those when possible.

Installation

Forwarding logs to Timber is highly specific to your HTTP client. Below are a few examples, as well as best practices. If possible, we recommend following our language, log forwarder, operating system, or platform integrations, as log delivery is handled for you in all of these.

Examples

http (bearer auth)
http (basic auth)
curl (bearer auth)
curl (basic auth)
POST https://logs.timber.io/sources/YOUR_SOURCE_ID/frames
Authorization: Bearer YOUR_API_KEY
Content-Type: application/ndjson
{"level": "debug", "message": "Testing the pipes"}
{"level": "debug", "message": "Testing the pipes again"}
POST https://user:YOUR_API_KEY@logs.timber.io/sources/YOUR_SOURCE_ID/frames
Content-Type: application/ndjson
{"level": "debug", "message": "Testing the pipes"}
{"level": "debug", "message": "Testing the pipes again"}

Timber will discard the user value. Basic auth required this. Use any value you'd like.

curl \
--request POST \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header "Content-Type: application/ndjson" \
--data '{"level": "debug", "message": "Testing the pipes"}
{"level": "debug", "message": "Testing the pipes again"}' \
https://logs.timber.io/sources/YOUR_SOURCE_ID/frames
curl \
--request POST \
--user "user:YOUR_API_KEY" \
--header "Content-Type: application/ndjson" \
--data '{"level": "debug", "message": "Testing the pipes"}
{"level": "debug", "message": "Testing the pipes again"}' \
https://logs.timber.io/sources/YOUR_SOURCE_ID/frames

Timber will discard the user value. Basic auth required this. Use any value you'd like.

Getting Your API Key And Source ID

If you haven't already, please create a Timber source by following the Sending Logs guide. Timber will display your API key and source ID immediately after you create a source.

Authorization

Timber requires the Authorization header as part of making requests to the Timber API. We support 2 strategies, the Bearer and Basic strategies.

Bearer Strategy

When choosing the Bearer strategy you can simply paste in your API key in its original form. You do not need to base 64 encode the key!

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5c...

Basic Strategy

When choosing the Basic strategy you must do 2 things:

  1. Prefix your API key with a user:

  2. Base 64 encode it.

Basic auth requires a user, any value you put as the user will be discarded by Timber, but you must supply some value.

For example, given this API key / user combination: user:eyJhbGciOiJIUzI1NiIsInR5c, you would supply the following header:

Authorization: Basic dXNlcjpleUpoYkdjaU9pSklVekkxTmlJc0luUjVj

Buffering & Batching

Always buffer and batch your log data to Timber. Do not send lines individually as this is extremely inefficient; you'll quickly tax your application. Timber recommends flushing your buffer every 2 seconds or until it's size reaches 950kb. Timber will not accept requests larger than 1mb.

Accepted Content Types

Timber accepts the following content types (ordered by preference):

Expected Response Codes

  1. 202 - Success, logs accepted.

  2. 400 - Request invalid, usually due to a bad content-type.

  3. 401 - API key invalid.

  4. 402 - Subscription blocked or unpaid. Please update your subscription.

  5. 500 - Timber service error.

Timber Libraries

If you don't want to do this yourself you can use one of Timber's language libraries.

Limitations

See the Limitations document for a comprehensive list.

Troubleshooting

To begin, please see our log delivery troubleshooting guide. This covers the most common issues we see with log delivery:

If the above guide does not resolve your issue please contact support.