Create a collector

Creates a new Better Stack collector.

The platform and data_region attributes can only be set during creation and cannot be updated later. A custom bucket can only be added during creation; its key pair can be rotated with Update collector.

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, and kubernetes.

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, as an object with the keys below.

custom_bucket.endpoint

required string

The full URL endpoint of the S3-compatible bucket, with no path after the bucket name.

Example: https://s3.us-east-1.amazonaws.com/storage-bucket.

custom_bucket.access_key_id

required string

The access key ID of the key pair that has permissions to access this bucket.

custom_bucket.secret_access_key

required string

The secret access key of the key pair that has permissions to access this bucket.

custom_bucket.keep_data_after_retention

boolean

Whether we should keep data in the bucket after the retention period instead of removing it. Defaults to false.

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.

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`.
`log_line_length_limit_kb`	integer	Logs longer than this will be dropped. Raising it may increase memory usage. Default 8, must be within 4-128 range.
`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. A component you leave out gets its default, the same value a create without components gets.

Key	Type	Description
`ebpf_java_agent`	Boolean	Inject the Java agent into JVMs for visibility into TLS connections, such as HTTPS and MySQL, in eBPF traces. Requires eBPF tracing and collector v1.1.46 or newer on every host. Defaults to `false`.
`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_cluster`	Boolean	Collect Kubernetes object state metrics, including pods, workloads, nodes and volumes.
`metrics_databases`	Boolean	Legacy alias of `metrics_cluster`. If you send both, `metrics_cluster` wins. Sent without `metrics_cluster`, it can also set whichever of `metrics_postgres`, `metrics_mysql`, `metrics_elasticsearch` and `metrics_pgbouncer` you leave out, so send those four explicitly.
`metrics_elasticsearch`	Boolean	Collect Elasticsearch metrics. Defaults to `true`.
`metrics_host_os`	Boolean	Collect CPU, memory, disk, filesystem and network metrics of the host with nodeexporter, independently of `ebpfmetrics`. Defaults to`true`.
`metrics_mysql`	Boolean	Collect MySQL metrics. Defaults to `true`.
`metrics_nginx`	Boolean	Collect Nginx metrics.
`metrics_other_databases`	Boolean	Collect Redis, MongoDB, Memcached and Kafka metrics, plus supplementary PostgreSQL, MySQL and connection pooler metrics.
`metrics_pgbouncer`	Boolean	Collect PgBouncer metrics. Defaults to `true`.
`metrics_postgres`	Boolean	Collect PostgreSQL metrics. Defaults to `true`.
`metrics_traefik`	Boolean	Collect Traefik metrics.
`traces_opentelemetry`	Boolean	Accept OpenTelemetry SDK traces on ports 4317 (gRPC) and 4318 (HTTP).

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_cluster": 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",
        "log_line_length_limit_kb": 8
      },
      "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_cluster": false
         },
         "vrl_transformation": ".message = downcase!(.message)",
         "when_full": "block",
         "log_line_length_limit_kb": 64
       }
     }'

Get a single collector

Update a collector

Explore documentation

Create a collector

Configuration Object

Components Object

Example: Basic Collector

Example: Collector with Configuration

Please accept cookies