Introduction

This guide explains how to configure and manage Astra Traffic Collector (ATC) on a Linux-based VM (AWS/GCP/Azure/DO). It includes step-by-step installation, customization, and troubleshooting common issues.

Prerequisites

1. Create Astra Traffic Collector integration and keep the secrets handy

   📄 How to Create Collector Integration for API Observability

2. A virtual machine where the Astra Traffic Collector can be installed

   1. Min system requirement: 2GB RAM, 2 CPU, 20GB Disk

   2. Docker and docker compose installed

Installation

Step 1 – SSH into the VM

Step 2 – Create a working directory

This directory will hold all configs and compose files.

mkdir -p /opt/astra-traffic-collector && cd /opt/astra-traffic-collector

Step 3 – Create docker-compose.yaml

Paste the following:

version: '3.3' 
services:
  my-service-init:
    image: busybox:1.35.0-uclibc
    user: root
    volumes:
      - collector-message:/tmp/message_data
    command: chown -R 10001:10001 /tmp/message_data
  otel-sensor:
    image: docker.io/getastra/traffic-collector
    container_name: astra-traffic-collector
    volumes:
      - collector-message:/var/lib/otelcol/file_storage:z
      - /opt/astra-traffic-collector/config_custom.yaml:/etc/otelcol-contrib/config_custom.yaml:ro
    network_mode: host
    env_file:
      - astra.env
    restart: always
    depends_on:
      - my-service-init
volumes:
  collector-message:

Step 4 – Create astra.env File

This file contains your ATC configuration and authentication credentials.

Replace the following values in the astra.env

COLLECTOR_ID=12345678-1234-4abc-9def-987654321000
CLIENT_ID=12345678-1234-4abc-9def-987654321000
CLIENT_SECRET=12345678-1234-4abc-9def-987654321000
TOKEN_URL=https://auth.getastra.com/realms/astra_api_scanner/protocol/openid-connect/token
REMOTE_ADDR_IDENTIFIER_HEADER=x-forwarded-for

Step 5 – Create config_custom.yaml

This config defines user defined trace filtering and transformation rule.

processors:

  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/filterprocessor
  filter/custom:
      error_mode: ignore
      traces:
        span:
          ## allowing traces based on hostname regex pattern. Following will drop all traces originated from host other than: localhost*
          #- IsMatch(attributes["url.host"], "localhost*") == false
          ## excluding traces based on hostname regex pattern. Following will drop all traces originated from host: localhost*
          #- IsMatch(attributes["url.host"], "localhost*")
          ## excluding traces based on template regex pattern. Following will drop all traces having url_template: _wdt*
          #- IsMatch(attributes["url.template"], "_wdt*")
           - ConvertCase(attributes["http.method"], "upper") == "OPTIONS"
  
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/transformprocessor
  transform/custom:
    error_mode: ignore
    trace_statements:
      - context: span
        statements:
          ## Templatize url path regex pattern by keyword: "slug". Following will templatize the url Path: /api/v1/products/details/prod-12r4ty   ->  /api/v1/products/details/{{product_id}}
          #- replace_pattern(attributes["url.template"], "prod-*", "{{product_id}}")
          ## Redact MasterCard credit card number
          - replace_all_patterns(attributes, "value", "^5[1-5][0-9]{14}$", "{{CreditCard}}")

service:
    pipelines:
      traces:
        exporters: [debug, otlp]

Step 6 – Create systemd Service

Create /etc/systemd/system/astra-traffic-collector.service

[Unit]
Description=Start Astra's traffic collectors
After=docker.service
Requires=docker.service

[Service]
Type=simple
ExecStart=/bin/bash -c "docker compose -f /opt/astra-traffic-collector/docker-compose.yaml up"
ExecStop=/bin/bash -c "docker compose -f /opt/astra-traffic-collector/docker-compose.yaml down"
Restart=always

[Install]
WantedBy=multi-user.target

Step 7 – Manage Service with systemctl

# Enable the service to start on boot
sudo systemctl enable astra-traffic-collector

# Start the service
sudo systemctl start astra-traffic-collector

# Restart the service
sudo systemctl restart astra-traffic-collector

# Check service status
sudo systemctl status astra-traffic-collector

Customizing the behavior of Astra Traffic Collector

Step 1 — Edit Custom Configuration

Modify /opt/astra-traffic-collector/config_custom.yaml to add filtering, redaction, or URL templating.

📄 How to customize the Astra Traffic collector

Step 2 — Apply the changes and restart the Astra Traffic Collector

sudo systemctl start astra-traffic-collector

Upgrade

Docker container upgrade

Execute the following commands to upgrade the Astra Traffic Collector

systemctl stop astra-traffic-collector
cd /opt/astra-traffic-collector/
docker-compose pull
systemctl start astra-traffic-collector

Troubleshooting & FAQ

Unable to Send Traces

Symptoms

• No new entries appear in the Inventory.

• Astra Traffic Collector logs show authentication errors such as:

error exporterhelper/queue_sender.go:92 Exporting failed... rpc error: code = Unauthenticated

Solution

1. Verify that the following values in astra.env are correct:

   • COLLECTOR_ID

   • CLIENT_ID

   • CLIENT_SECRET

2. Update the values if required.

3. Restart Astra Traffic Collector.

   systemctl restart astra-traffic-collector

Inventory Is Not Updating or New Endpoints Are Not Appearing

Symptoms

• Inventory remains unchanged.

• Newly accessed endpoints are not discovered.

• No errors are visible in Astra Traffic Collector logs.

Solution

1. Ensure the hostname is listed under Scope URI in the target configuration.

2. If the hostname is not listed, add it under Extra Hosts in the Astra UI.

3. Generate traffic again and verify endpoint discovery.

How Do I Regenerate the Client Secret for an Astra Traffic Collector Integration?

Solution

Follow the steps in:

📄 How to Create Collector Integration for API Observability

How to Create Collector Integration for API Observability

1. Update the newly generated credentials in astra.env.

2. Restart Astra Traffic Collector.

systemctl restart astra-traffic-collector