ASAPCollector

Design documents, developer workflows, and operator guides are indexed in the ASAPCollector documentation.

Metrics Collection Pipeline Deployments

Table 1: Example deployment options

Deployment stage / Example pipeline	Instrumentation	Agent aggregation (optional)	Gateway aggregation (optional)	Backend databases / storage
Prometheus scrape pipeline	Prometheus client libraries	OpenTelemetry Collector (agent mode scraping or Prometheus remote_write)	OpenTelemetry Collector (gateway mode for routing, batching, export fan-out)	Prometheus TSDB / Thanos / Mimir InfluxDB / IOx / VictoriaMetrics TimescaleDB / ClickHouse / BigQuery / other OTLP-compatible sinks
Telegraf + Influx pipeline	Influx Line Protocol emitters	Telegraf Agent (local metric/log aggregation)	OpenTelemetry Collector (via ILP receiver if available, or via intermediary like Kafka/HTTP → OTLP)
Native OTLP pipeline	OpenTelemetry SDK (OTLP exporters)	OpenTelemetry Collector (sidecar or daemonset agent)	OpenTelemetry Collector (centralized gateway: auth, routing, tail-sampling)

Table 2: All Possible Deployment Combinations

Instrumentation	Local agent	Gateway (optional)	Backend storage
• Prometheus client libraries • OpenTelemetry SDK • Influx Line Protocol emitters	• OpenTelemetry Collector (agent mode scraping) • Telegraf scraping Prometheus endpoints • Kafka	OpenTelemetry Collector Routing, auth, tail-sampling, multi-backend fan-out	Prometheus TSDB / Thanos / Mimir / InfluxDB / IOx / VictoriaMetrics / TimescaleDB / ClickHouse / BigQuery / OTLP sinks

Initial Setup

After cloning, run the one-time setup script to install Go, the OCB builder, and initialise submodules:

./setup.sh

If Go is already managed externally (e.g. via asdf, mise, or a system package):

./setup.sh --no-go

The script is safe to re-run: each step is skipped when already satisfied.

Flag	Effect
--no-go	Skip Go download/installation

---

Cloning

Clone with the OTel submodules needed by the MVP:

git clone git@github.com:ProjectASAP/ASAPCollector.git
# or
git clone https://github.com/ProjectASAP/ASAPCollector.git

If you have an existing clone, initialize the OTel submodules:

cd ASAPCollector
git submodule update --init opentelemetry-collector opentelemetry-collector-contrib opentelemetry-go opentelemetry-proto

Working with the OpenTelemetry submodule

Code organization

opentelemetry-go/                       # upstream Go SDK submodule
opentelemetry-collector/                # upstream collector core checkout
opentelemetry-collector-contrib/        # upstream contrib components
opentelemetry-proto/                    # upstream OTLP proto definitions

opentelemetry-go-patch/                 # tracked overlay of our SDK changes
opentelemetry-collector-patch/          # tracked overlay of collector-core tweaks
opentelemetry-collector-contrib-patch/  # tracked overlay of contrib-only tweaks
opentelemetry-proto-patch/              # tracked overlay of proto changes

Build and Test Cheat Sheet

opentelemetry-proto

cd opentelemetry-proto
make gen-go

Collector core (opentelemetry-collector)

1. Regenerate protobuf + pdata after touching proto specs:

   cd opentelemetry-collector
   make genproto
   make genpdata

2. Build the opentelemetry-collector binary:

   make otelcol

3. Run Go tests:

   go test ./... -count=1

Collector-contrib distributions (opentelemetry-collector-contrib-patch)

Important: The OCB builder version must match the distribution target version. The asap-otel distribution targets v0.141.0, so OCB v0.141.0 is required. Using a newer builder (e.g. v0.147.0) injects incompatible runtime sub-modules.

Quick build (recommended)

Use the provided script from the repo root — it handles the builder version automatically:

./build_asap_otel.sh

The binary is written to:

opentelemetry-collector-contrib-patch/cmd/asap-otel/asap-otel

Manual build steps

# 1. Install the matching OCB builder version
go install go.opentelemetry.io/collector/cmd/builder@v0.141.0

# 2. Build
cd opentelemetry-collector-contrib-patch
builder --config ./cmd/asap-otel/builder-config.yaml

Go SDK / exporters (opentelemetry-go)

1. Format and tidy after edits:

   gofmt -w ./...
   go mod tidy

2. Run tests (ensure this repo is loaded as the module root):

   go test ./...

3. To mirror changes into the tracked overlay, copy updated files into opentelemetry-go-patch/ before committing.

otel-app

cd otel-app
go build -o otel-app .            # produces ./otel-app
# or to run in-place:
go run .