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_group_id

integer

The ID of the resource group to assign the collector's associated sources to.

live_tail_pattern

string

A custom format for messages displayed in live tail, with columns wrapped in {column} brackets.
Example: "PID: {message_json.pid} {level} {message}".
For details, see Live tail docs.

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. See the Components Object section below for a full list.
`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).

Components Object

The components object is a flat map of boolean flags to enable or disable specific data collection features.

Key	Type	Description
`ebpf_metrics`	Boolean	Enable eBPF-based metrics collection.
`ebpf_red_metrics`	Boolean	Enable service map and RED (Requests, Error rate, Duration) metrics via eBPF.
`ebpf_tracing_basic`	Boolean	Enable basic eBPF tracing.
`ebpf_tracing_full`	Boolean	Enable full eBPF tracing.
`logs_collector_internals`	Boolean	Collect internal collector logs.
`logs_docker`	Boolean	Collect Docker container logs.
`logs_host`	Boolean	Collect host-level logs.
`logs_kubernetes`	Boolean	Collect Kubernetes logs.
`metrics_apache`	Boolean	Collect Apache metrics.
`metrics_databases`	Boolean	Collect database metrics via the cluster agent.
`metrics_nginx`	Boolean	Collect Nginx metrics.
`traces_opentelemetry`	Boolean	Accept OpenTelemetry SDK traces on ports 4317 (gRPC) and 4318 (HTTP).

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": {
          "ebpf_metrics": true,
          "ebpf_red_metrics": true,
          "ebpf_tracing_full": true,
          "logs_kubernetes": true,
          "metrics_databases": true,
          "traces_opentelemetry": 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,
      "source_id": 12345,
      "source_group_id": null,
      "live_tail_pattern": 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

Copied!

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

Copied!

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,
           "ebpf_red_metrics": true,
           "ebpf_tracing_full": true,
           "logs_kubernetes": true,
           "metrics_databases": false
         },
         "vrl_transformation": ".message = downcase!(.message)",
         "when_full": "block"
       }
     }'

Example: Proxy Collector with HTTP Basic Auth

cURL

Copied!

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"
       }
     }'

Get a single collector

Update a collector

Explore documentation

Create a collector

Configuration Object

Components Object

Proxy Configuration Object

Example: Basic Collector

Example: Collector with Configuration

Example: Proxy Collector with HTTP Basic Auth

Please accept cookies