Explore documentation
  1. Welcome to Telemetry 👋
  2. Quick start guide
  3. Wide events vs. metrics
  4. Ingesting data
    1. Better Stack collector
    2. Vector
    3. OpenTelemetry
    4. Ingesting via HTTP API
    5. Ingesting metrics
    6. Ingesting logs
    7. Migrating to Better Stack
  5. Using the product
    1. AI SRE ↗
    2. MCP server ↗
    3. Transforming ingested data
    4. Querying data
    5. Tracing
    6. Alerts
  6. Telemetry API
    1. Getting an API token
    2. Sources API
    3. Source groups API
    4. Metrics API
    5. Dashboards API
    6. Connections API
    7. Collectors API
      1. List all collectors GET
      2. Get a single collector GET
      3. Create a collector POST
      4. Update a collector PATCH
      5. Remove a collector DELETE
      6. List hosts where a collector is running GET
      7. Lists databases monitored by a collector GET
    8. Query API ↗
  7. Alternative to
    1. Lightstep

Create a collector

Creates a new Better Stack collector.

The platform, data_region, and custom_bucket attributes can only be set during creation and cannot be updated later.

POST https://telemetry.betterstack.com/api/v1/collectors

Headers

Authorization
required string

Bearer $TOKEN

Body parameters

name
required string

A unique name for the collector.

platform
required string

The platform where the collector will be installed. Valid options are docker, swarm, kubernetes, and proxy.

note
string

An optional note for the collector.

team_name
string

Required if using a global API token to specify the team that will own the collector.

data_region
string

The data region where the collector's data will be stored. If omitted, the organization's default region is used.

logs_retention
integer

Custom retention period for logs, in days. This is only available on select plans.

metrics_retention
integer

Custom retention period for metrics, in days. This is only available on select plans.

ingesting_paused
boolean

Set to true to create the collector in a paused state, preventing it from ingesting data.

source_vrl_transformation
string

A VRL program to be applied to logs server-side during ingestion.

custom_bucket
object

Configuration for storing data in your own S3-compatible bucket. This is only available on select plans.

user_vector_config
string

A custom Vector configuration in YAML format to be merged with the collector's generated configuration.

configuration
object

An object containing detailed configuration options for the collector.

proxy_config
object

An object containing settings specific to the proxy platform, such as buffering, SSL/TLS, and HTTP Basic Auth.

databases
array

An array of database connection objects to be monitored by the collector.

Configuration Object

The configuration object allows for fine-grained control over the collector's behavior.

Key Type Description
components object A flat object of boolean flags to enable or disable specific data collection components (e.g., ebpf_metrics: true, logs_docker: false).
logs_sample_rate integer The percentage (0-100) of logs to sample.
traces_sample_rate integer The percentage (0-100) of traces to sample.
vrl_transformation string A VRL program to transform telemetry data on the host before sending.
disk_batch_size_mb integer The maximum size (in MB) of on-disk batches. Minimum is 256.
memory_batch_size_mb integer The maximum size (in MB) of in-memory batches.
when_full string The buffer overflow strategy. Valid options are drop_newest (default) and block.
services_options object Per-service overrides for log sampling and trace ingestion.
namespaces_options object Per-namespace overrides for log sampling and trace ingestion (Kubernetes only).

Proxy Configuration Object

The proxy_config object is only applicable when platform is proxy.

Key Type Description
enable_buffering_proxy boolean Enables the collector to act as a buffering proxy.
buffering_proxy_listen_on string The address and port to listen on (e.g., 0.0.0.0:8080).
enable_ssl_certificate boolean Enables SSL/TLS termination using a Let's Encrypt certificate.
ssl_certificate_host string The hostname for the SSL certificate.
enable_http_basic_auth boolean Enables HTTP Basic Authentication for incoming requests.
http_basic_auth_username string The username for HTTP Basic Auth.
http_basic_auth_password string The password for HTTP Basic Auth. This value is write-only and will not be returned in any API response.
201

The collector was created successfully.

Response body

{
  "data": {
    "id": "2",
    "type": "collector",
    "attributes": {
      "name": "New API Collector",
      "platform": "kubernetes",
      "note": "Created via API for testing.",
      "status": "offline",
      "secret": "new-collector-secret-goes-here",
      "team_id": 123,
      "team_name": "My Team",
      "data_region": "a3",
      "logs_retention": 30,
      "metrics_retention": 90,
      "configuration": {
        "components": {
          "logs_kubernetes": true
        },
        "logs_sample_rate": 100,
        "traces_sample_rate": 100,
        "vrl_transformation": null,
        "disk_batch_size_mb": 256,
        "memory_batch_size_mb": 10,
        "when_full": "drop_newest"
      },
      "proxy_config": null,
      "user_vector_config": null,
      "ingesting_paused": false,
      "source_vrl_transformation": null,
      "pinged_at": null,
      "created_at": "2023-10-28T12:00:00.000Z",
      "updated_at": "2023-10-28T12:00:00.000Z",
      "custom_bucket": null
    }
  }
}
422

Validation failed due to invalid parameters.

Response body

{
  "errors": [
    "name has already been taken"
  ],
  "invalid_attributes": [
    "name"
  ]
}

Example: Basic Collector

cURL
curl -X POST "https://telemetry.betterstack.com/api/v1/collectors" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "My Docker Collector",
       "platform": "docker",
       "note": "For staging environment services."
     }'


Example: Collector with Configuration

cURL
curl -X POST "https://telemetry.betterstack.com/api/v1/collectors" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Configured K8s Collector",
       "platform": "kubernetes",
       "configuration": {
         "components": {
           "ebpf_metrics": true,
           "logs_kubernetes": true,
           "metrics_databases": false
         },
         "vrl_transformation": ".message = downcase!(.message)",
         "when_full": "block"
       }
     }'


Example: Proxy Collector with HTTP Basic Auth

cURL
curl -X POST "https://telemetry.betterstack.com/api/v1/collectors" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Secure Proxy Collector",
       "platform": "proxy",
       "proxy_config": {
         "enable_buffering_proxy": true,
         "buffering_proxy_listen_on": "0.0.0.0:8080",
         "enable_http_basic_auth": true,
         "http_basic_auth_username": "proxy_user",
         "http_basic_auth_password": "a-very-secret-password"
       }
     }'


Previous article

Get a single collector

Next article

Update a collector