ADSB2Otel

🚀 A Go service that fetches aircraft data generated by dump1090-fa and streams it via OpenTelemetry (OTLP) for real-time monitoring and analysis.

Prerequisites

• dump1090-fa instance (such as piAware or ADS-B Feeder)
• OpenTelemetry-compatible backend

Demo

You can view live aircraft data from an aerial located in Bristol, UK on our Grafana Dashboard found here.

Configuration

Create a .env file in the project root with the following variables:

FLIGHT_DATA_URL=http://your-flightdata-instance/data/aircraft.json

# Shared OpenTelemetry Configuration (applies to both logs and traces)
OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4318
OTEL_EXPORTER_OTLP_PROTOCOL=http
OTEL_EXPORTER_OTLP_INSECURE=true
OTEL_EXPORTER_OTLP_HEADERS=

# OpenTelemetry Logs Configuration
OTEL_LOGS_ENABLED=true

# OpenTelemetry Tracing Configuration (Optional)
OTEL_TRACING_ENABLED=true

# Application Logging Configuration
LOG_LEVEL=info

OpenTelemetry Configuration

The application uses OpenTelemetry Protocol (OTLP) to send logs and traces to any compatible backend. It follows the OpenTelemetry specification by using shared environment variables for common settings, with signal-specific overrides when needed.

Shared Environment Variables (Recommended)

These apply to both logs and traces:

• OTEL_EXPORTER_OTLP_ENDPOINT: OTLP endpoint (default: localhost:4318)
• OTEL_EXPORTER_OTLP_PROTOCOL: Protocol to use - http or grpc (default: http)
• OTEL_EXPORTER_OTLP_INSECURE: Set to true for insecure connections (default: true)
• OTEL_EXPORTER_OTLP_HEADERS: Headers for export (format: key1=value1,key2=value2)

Signal-Specific Overrides

You can override shared settings for specific signals if needed:

For Logs:

• OTEL_EXPORTER_OTLP_LOGS_ENDPOINT: Override endpoint for logs only
• OTEL_EXPORTER_OTLP_LOGS_PROTOCOL: Override protocol for logs only
• OTEL_EXPORTER_OTLP_LOGS_INSECURE: Override insecure setting for logs only
• OTEL_EXPORTER_OTLP_LOGS_HEADERS: Override headers for logs only

For Traces:

• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: Override endpoint for traces only
• OTEL_EXPORTER_OTLP_TRACES_INSECURE: Override insecure setting for traces only
• OTEL_EXPORTER_OTLP_TRACES_HEADERS: Override headers for traces only

Protocol Support

• HTTP/Protobuf (default): Use OTEL_EXPORTER_OTLP_PROTOCOL=http
• gRPC: Use OTEL_EXPORTER_OTLP_PROTOCOL=grpc

Authentication

For authenticated backends, use the shared OTEL_EXPORTER_OTLP_HEADERS environment variable:

OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer token,api-key=key

Logging Configuration

The application uses structured logging in logfmt format with configurable log levels.

Log Levels

Set the LOG_LEVEL environment variable to control logging verbosity:

• debug: Shows all logs including debug calls, environment variables, and HTTP requests
• info: Shows info, warn, and error logs (default)
• warn: Shows only warning and error logs
• error: Shows only error logs

OpenTelemetry Tracing Configuration

The application supports distributed tracing using OpenTelemetry. This is optional and disabled by default.

Environment Variables

• OTEL_TRACING_ENABLED: Set to true or 1 to enable tracing

Tracing uses the shared OTEL_EXPORTER_OTLP_* environment variables (see above). You can override with OTEL_EXPORTER_OTLP_TRACES_* variables if needed.

Trace Information

When tracing is enabled, the application will create spans for:

• Main fetch cycle: Overall operation span (flightdata.fetch_and_push)
• HTTP data fetch: Fetching aircraft data from dump1090-fa
• JSON parsing: Parsing the aircraft data
• Log emission: Emitting OpenTelemetry log records

Each span includes relevant attributes like HTTP status codes, durations, aircraft counts, and error information. Logs are automatically correlated with traces when both are enabled.

Installation

Building from Source

1. Clone the repository:

git clone https://github.com/burnettdev/adsb2otel.git
cd adsb2otel

2. Install dependencies:

go mod tidy

3. Build the application:

go build -o adsb2otel

4. Run the application:

./adsb2otel

Docker

Build and run with Docker:

# Build the image
docker build -t adsb2otel .

# Run the container
docker run -d \
  --name adsb2otel \
  -e FLIGHT_DATA_URL=http://your-flightdata-instance/data/aircraft.json \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4318 \
  -e OTEL_EXPORTER_OTLP_PROTOCOL=http \
  -e OTEL_TRACING_ENABLED=true \
  --restart unless-stopped \
  adsb2otel

Pull from Github Container Registry:

# Run the container
docker run -d \
  --name adsb2otel \
  -e FLIGHT_DATA_URL=http://your-flightdata-instance/data/aircraft.json \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4318 \
  -e OTEL_EXPORTER_OTLP_PROTOCOL=http \
  -e OTEL_TRACING_ENABLED=true \
  --restart unless-stopped \
  ghcr.io/burnettdev/adsb2otel:latest

Usage

The service will:

• Fetch aircraft data every 5 seconds
• Emit OpenTelemetry log records for each aircraft
• Automatically correlate logs with traces (if tracing is enabled)
• Log any errors that occur during the process

Data Structure

Each aircraft entry is sent as an OpenTelemetry log record with:

• Timestamp: When the aircraft data was captured
• Body: Full aircraft data as JSON
• Attributes: Structured metadata including:
  • service: "adsb"
  • aircraft.hex: Aircraft transponder hex code
  • aircraft.type: Aircraft type
  • aircraft.flight: Flight number (if available)
  • aircraft.lat: Latitude (if available)
  • aircraft.lon: Longitude (if available)
  • aircraft.alt_baro: Barometric altitude (if available)
  • aircraft.squawk: Squawk code (if available)

Contributing

Feel free to open issues or submit pull requests!

License

MIT License - feel free to use this project for whatever you'd like!

Migration from Loki

If you were previously using the direct Loki integration, the service now uses OpenTelemetry Protocol (OTLP) instead. To route logs to Loki, use an OpenTelemetry Collector with a Loki exporter, or use Grafana Cloud which accepts OTLP directly.

ADSB2Otel is proudly part of Snyk's Open Source Programme, ensuring vulnerabilities are found sooner rather than later. You can find more information here.