Overview

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

Quick 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

Issue 1 — Unable to Send Traces

Symptoms

• No new entries in the inventory.

• Logs show authentication errors:

  📄 Verifying Traces in Astra Traffic Collector

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

Cause
Invalid COLLECTOR_ID or CLIENT_ID or CLIENT_SECRET in astra.env.

Solution

• Update astra.env with correct credentials.

• Restart Astra Traffic Collector

  systemctl restart astra-traffic-collector

Issue 2 — No Inventory Updates but No Errors

Symptoms

• Inventory remains static. (not getting changed or new endpoints are not shown)

• No errors in ATC logs.

Cause

• Unregistered hostname or wrong scopeURL.

Solution

• Ensure the hostname is listed under Scope URI in the target setup.

• If not, add it under Extra Hosts in the Astra UI.

FAQ (Frequently Asked Questions)

1. Can I see what trace are sent from my environment?

   📄 Verifying Traces in Astra Traffic Collector

2. How to regenerate client secret for astra-traffic-collector integration?

   📄 How to Create Collector Integration for API Observability

   1. Update the newly created secrets in astra.env

   2. Restart Astra Traffic Collector

      systemctl restart astra-traffic-collector