Introduction

This article helps you configure the Astra Traffic Collector for traffic monitoring on your macOS machine. This setup allows you to capture and process telemetry data from your APIs directly from your local environment.

Prerequisites

• You must have created an Astra Traffic Collector integration in your Astra Dashboard to obtain your Collector ID, Client ID, and Client Secret.

• Docker Desktop version 4.34 or later must be installed on your machine.

• You must enable Host Network Mode in Docker Desktop:

  1. Navigate to Settings in Docker Desktop.

  2. Under the Resources tab, select Network.

• Check the Enable host networking option and click Apply and restart.

Instructions

Step 1: Prerequisites

Before proceeding, ensure the following are in place:

1. SSH into the VM where you intend to run the Traffic Collector.

2. Install Docker Desktop version 4.34 or later on your machine. See the official Docker Desktop installation guide for steps.

3. Enable host network mode in Docker Desktop, which is required for the collector to function correctly:

   1. Sign in to your Docker account in Docker Desktop.

   2. Navigate to Settings.

   3. Under the Resources tab, select Network.

   4. Check Enable host networking.

   5. Select Apply and restart.

Step 2: Create a Working Directory

Mac systems restrict which paths can be used for Docker volume mounting. Use /var or /tmp as your working directory.

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

Step 3: Create the docker-compose.yaml File

Create a file named docker-compose.yaml in your working directory with the following content:

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:
    platform: linux/amd64
    image: docker.io/getastra/traffic-collector
    container_name: astra-traffic-collector
    volumes:
      - "collector-message:/var/lib/otelcol/file_storage:z"
      - "/var/astra-traffic-collector/config_custom.yaml:/etc/otelcol-contrib/config_custom.yaml:ro"
    network_mode: host
    env_file:
      - .env
    restart: always
    depends_on:
      - my-service-init
volumes:
  collector-message:

Step 4: Create the .env File

Create a file named .env in your working directory. Fill in the values displayed during the creation of your Astra Traffic Collector integration in the Astra Dashboard:

COLLECTOR_ID — displayed during Traffic Collector integration setup

CLIENT_ID — displayed during Traffic Collector integration setup

CLIENT_SECRET — displayed during Traffic Collector integration setup

COLLECTOR_ID=
CLIENT_ID=
CLIENT_SECRET=
TOKEN_URL=https://auth.getastra.com/realms/astra_api_scanner/protocol/openid-connect/token
REMOTE_ADDR_IDENTIFIER_HEADER=x-forwarded-for

Step 5: Create the config_custom.yaml File

Create a file named config_custom.yaml in your working directory. This file defines trace filtering and transformation rules applied before data is sent to Astra.

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*")
        ## exclude traces with method set to OPTIONS. Comment below line to allow the traces with http method OPTIONS
        - 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/chinchikrqwertyuiop/ -> /api/v1/{{slug}}/
          - replace_pattern(attributes["url.template"], "chinchikrqwertyuiop", "{{slug}}")
          ## Redact MasterCard credit card number 
          #- replace_all_patterns(attributes, "value", "^5[1-5][0-9]{14}$", "{{card}}")

Step 6: Launch the Service

Once all three files are in place, start the collector:

docker compose up -d

To stop the service:

docker compose down

To check the container status:

docker ps -a

To check logs:

docker logs astra-traffic-collector

Expected Outcome

After running docker compose up -d, run docker ps -a. You should see the astra-traffic-collector container with a status of Up. Traces will begin processing and appearing in your Astra Dashboard for inventory and scanning.

Troubleshooting & Common Issues

• Container Status "Exited": This often indicates an issue with your .env file. Double-check that your CLIENT_ID and CLIENT_SECRET are correct and that there are no extra spaces.

• Permission Errors: If you encounter volume mount errors, ensure you are using the recommended /var or /tmp directories, as Mac may block other paths.

• Inspecting Logs: To see real-time activity or identify errors, use the following command:

  • docker logs astra-traffic-collector

• Image Pull Failures (Mac ARM): If the image fails to pull on a Mac with an M1/M2/M3 chip, manually pull the compatible version first:

  • docker pull --platform linux/x86_64 getastra/traffic-collector

•  version 4.34 or later must be installed on your machine.

• You must enable Host Network Mode in Docker Desktop:

  1. Navigate to Settings in Docker Desktop.

  2. Under the Resources tab, select Network.

  3. Check the Enable host networking option and click Apply and restart.