Skip to content

README.md

Latest commit

 

History

History
213 lines (178 loc) · 5.75 KB

README.md

File metadata and controls

213 lines (178 loc) · 5.75 KB
Raw

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 .