Explore documentation
  1. Welcome to Telemetry 👋
  2. Quick start guide
  3. Wide events vs. metrics
  4. Ingesting data
    1. Better Stack collector
    2. OpenTelemetry
    3. Vector
    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. Grafana
    7. Alerts
  6. Telemetry API
    1. Getting an API token
    2. Sources & collectors
      1. Sources API
      2. 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
      3. Collector metrics targets API
      4. Metrics API
      5. Source groups API
    3. Dashboards
    4. Explorations
    5. Alerts API
    6. Connections API
    7. Query API ↗
    8. Usage API ↗
  7. Alternative to
    1. Lightstep

Update a collector

Updates an existing collector. Only the provided parameters will be changed.

The platform and data_region attributes are immutable and cannot be changed after a collector is created. A custom bucket can only be added when creating a collector.

PATCH https://telemetry.betterstack.com/api/v1/collectors/{id}

URL parameters

id
required string

The unique identifier of the collector to update.

Headers

Authorization
required string

Bearer $TOKEN

Body parameters

name
string

A new unique name for the collector.

note
string

A new note for the collector. Send null to clear the existing note.

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 pause data ingestion, or false to resume.

source_group_id
integer

The ID of the resource group to assign the collector's associated sources to. Send 0 or null to remove the assignment.

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}". Send null to clear.
For details, see Live tail docs.

source_vrl_transformation
string

A VRL program to be applied to logs server-side. Send null to remove.

user_vector_config
string

A custom Vector configuration in YAML format. Send null to remove.

configuration
object

An object containing detailed configuration options to update. Only the keys provided in this object will be modified, including inside components. For a full list of options, see the configuration object section in the Create collector API documentation. Send false in components to turn a component off. If you send the legacy metrics_databases 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.

databases
array

An array of database objects to add, update, or remove. To remove a database, include its id and set _destroy: true.

custom_bucket
object

Rotates the key pair of the custom bucket the collector already uses. Send only access_key_id and secret_access_key. We verify the new pair against the bucket first; if that fails, the whole request is rejected with a 422 and nothing is changed. A bucket shared with other collectors or sources is rotated for all of them. Send the new pair before deactivating the old one to rotate without downtime.

Updating Databases

To manage monitored databases, provide an array to the databases parameter. Each object in the array can either update an existing database (by providing its id) or create a new one (by omitting the id). To delete a database, include its id and set _destroy: true.

Example `databases` payload
{
  "databases": [
    { "id": 1, "host": "updated-db.example.com" },
    { "service_type": "redis", "host": "new-redis.example.com", "port": 6379 },
    { "id": 2, "_destroy": true }
  ]
}
200

The collector was updated successfully.

Response body

{
  "data": {
    "id": "1",
    "type": "collector",
    "attributes": {
      "name": "Renamed Collector",
      "platform": "docker",
      "note": "This note has been updated.",
      "status": "online",
      "secret": "collector-secret-goes-here",
      "team_id": 123,
      "team_name": "My Team",
      "data_region": "a3",
      "logs_retention": 60,
      "metrics_retention": 180,
      "configuration": {
        "components": {
          "logs_docker": true,
          "ebpf_metrics": false
        },
        "logs_sample_rate": 50,
        "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": 678,
      "live_tail_pattern": "Updated pattern: {level}",
      "pinged_at": "2023-10-27T10:00:00.000Z",
      "created_at": "2023-10-26T10:00:00.000Z",
      "updated_at": "2023-10-28T14:00:00.000Z",
      "custom_bucket": null
    }
  }
}
404

A collector with the specified ID was not found.

422

Validation failed due to invalid or unsupported parameters.

Response body

{
  "errors": [
    "Data region can't be changed. Create a new collector to change your data region."
  ],
  "invalid_attributes": [
    "data_region"
  ]
}

Example Request

cURL
curl -X PATCH "https://telemetry.betterstack.com/api/v1/collectors/1" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "note": "Updated note for production collector.",
       "configuration": {
         "components": {
           "ebpf_metrics": false
         },
         "logs_sample_rate": 50
       }
     }'


Previous article

Create a collector

Next article

Remove a collector