Add AGENTS.md for AI coding assistant onboarding #7700

Copilot · 2025-12-05T16:07:38Z

No description provided.

AGENTS.md

codecov · 2025-12-06T03:47:56Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.54%. Comparing base (5b10a21) to head (2abd25d).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #7700   +/-   ##
=======================================
  Coverage   96.54%   96.54%           
=======================================
  Files         384      384           
  Lines       19511    19511           
=======================================
  Hits        18837    18837           
  Misses        489      489           
  Partials      185      185

Flag	Coverage Δ
badger_v1	`8.81% <ø> (ø)`
badger_v2	`1.72% <ø> (ø)`
cassandra-4.x-v1-manual	`12.54% <ø> (ø)`
cassandra-4.x-v2-auto	`1.71% <ø> (ø)`
cassandra-4.x-v2-manual	`1.71% <ø> (ø)`
cassandra-5.x-v1-manual	`12.54% <ø> (ø)`
cassandra-5.x-v2-auto	`1.71% <ø> (ø)`
cassandra-5.x-v2-manual	`1.71% <ø> (ø)`
clickhouse	`1.65% <ø> (ø)`
elasticsearch-6.x-v1	`16.73% <ø> (ø)`
elasticsearch-7.x-v1	`16.76% <ø> (ø)`
elasticsearch-8.x-v1	`16.91% <ø> (ø)`
elasticsearch-8.x-v2	`1.72% <ø> (ø)`
elasticsearch-9.x-v2	`1.72% <ø> (ø)`
grpc_v1	`10.77% <ø> (ø)`
grpc_v2	`1.72% <ø> (ø)`
kafka-3.x-v1	`10.24% <ø> (ø)`
kafka-3.x-v2	`1.72% <ø> (ø)`
memory_v2	`1.72% <ø> (ø)`
opensearch-1.x-v1	`16.81% <ø> (ø)`
opensearch-2.x-v1	`16.81% <ø> (ø)`
opensearch-2.x-v2	`1.72% <ø> (ø)`
opensearch-3.x-v2	`1.72% <ø> (ø)`
query	`1.72% <ø> (ø)`
tailsampling-processor	`0.49% <ø> (ø)`
unittests	`95.45% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

github-actions · 2025-12-06T03:50:00Z

Metrics Comparison Summary

Total changes across all snapshots: 106

Detailed changes per snapshot

summary_metrics_snapshot_cassandra

📊 Metrics Diff Summary

Total Changes: 53

🆕 Added: 53 metrics
❌ Removed: 0 metrics
🔄 Modified: 0 metrics

🆕 Added Metrics

http_server_request_body_size_bytes (18 variants)

View diff sample

+http_server_request_body_size_bytes{http_request_method="GET",http_response_status_code="503",le="+Inf",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
+http_server_request_body_size_bytes{http_request_method="GET",http_response_status_code="503",le="0",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
+http_server_request_body_size_bytes{http_request_method="GET",http_response_status_code="503",le="10",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
+http_server_request_body_size_bytes{http_request_method="GET",http_response_status_code="503",le="100",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
+http_server_request_body_size_bytes{http_request_method="GET",http_response_status_code="503",le="1000",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
+http_server_request_body_size_bytes{http_request_method="GET",http_response_status_code="503",le="10000",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
+http_server_request_body_size_bytes{http_request_method="GET",http_response_status_code="503",le="25",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
...

- `http_server_request_duration_seconds` (17 variants)

View diff sample

+http_server_request_duration_seconds{http_request_method="GET",http_response_status_code="503",le="+Inf",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
+http_server_request_duration_seconds{http_request_method="GET",http_response_status_code="503",le="0.005",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
+http_server_request_duration_seconds{http_request_method="GET",http_response_status_code="503",le="0.01",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
+http_server_request_duration_seconds{http_request_method="GET",http_response_status_code="503",le="0.025",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
+http_server_request_duration_seconds{http_request_method="GET",http_response_status_code="503",le="0.05",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
+http_server_request_duration_seconds{http_request_method="GET",http_response_status_code="503",le="0.075",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
+http_server_request_duration_seconds{http_request_method="GET",http_response_status_code="503",le="0.1",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
...

- `http_server_response_body_size_bytes` (18 variants)

View diff sample

+http_server_response_body_size_bytes{http_request_method="GET",http_response_status_code="503",le="+Inf",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
+http_server_response_body_size_bytes{http_request_method="GET",http_response_status_code="503",le="0",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
+http_server_response_body_size_bytes{http_request_method="GET",http_response_status_code="503",le="10",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
+http_server_response_body_size_bytes{http_request_method="GET",http_response_status_code="503",le="100",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
+http_server_response_body_size_bytes{http_request_method="GET",http_response_status_code="503",le="1000",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
+http_server_response_body_size_bytes{http_request_method="GET",http_response_status_code="503",le="10000",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
+http_server_response_body_size_bytes{http_request_method="GET",http_response_status_code="503",le="25",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
...

### summary_metrics_snapshot_cassandra ## 📊 Metrics Diff Summary

Total Changes: 53

🆕 Added: 0 metrics
❌ Removed: 53 metrics
🔄 Modified: 0 metrics

❌ Removed Metrics

http_server_request_body_size_bytes (18 variants)

View diff sample

-http_server_request_body_size_bytes{http_request_method="GET",http_response_status_code="503",le="+Inf",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
-http_server_request_body_size_bytes{http_request_method="GET",http_response_status_code="503",le="0",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
-http_server_request_body_size_bytes{http_request_method="GET",http_response_status_code="503",le="10",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
-http_server_request_body_size_bytes{http_request_method="GET",http_response_status_code="503",le="100",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
-http_server_request_body_size_bytes{http_request_method="GET",http_response_status_code="503",le="1000",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
-http_server_request_body_size_bytes{http_request_method="GET",http_response_status_code="503",le="10000",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
-http_server_request_body_size_bytes{http_request_method="GET",http_response_status_code="503",le="25",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
...

- `http_server_request_duration_seconds` (17 variants)

View diff sample

-http_server_request_duration_seconds{http_request_method="GET",http_response_status_code="503",le="+Inf",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
-http_server_request_duration_seconds{http_request_method="GET",http_response_status_code="503",le="0.005",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
-http_server_request_duration_seconds{http_request_method="GET",http_response_status_code="503",le="0.01",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
-http_server_request_duration_seconds{http_request_method="GET",http_response_status_code="503",le="0.025",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
-http_server_request_duration_seconds{http_request_method="GET",http_response_status_code="503",le="0.05",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
-http_server_request_duration_seconds{http_request_method="GET",http_response_status_code="503",le="0.075",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
-http_server_request_duration_seconds{http_request_method="GET",http_response_status_code="503",le="0.1",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
...

- `http_server_response_body_size_bytes` (18 variants)

View diff sample

-http_server_response_body_size_bytes{http_request_method="GET",http_response_status_code="503",le="+Inf",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
-http_server_response_body_size_bytes{http_request_method="GET",http_response_status_code="503",le="0",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
-http_server_response_body_size_bytes{http_request_method="GET",http_response_status_code="503",le="10",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
-http_server_response_body_size_bytes{http_request_method="GET",http_response_status_code="503",le="100",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
-http_server_response_body_size_bytes{http_request_method="GET",http_response_status_code="503",le="1000",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
-http_server_response_body_size_bytes{http_request_method="GET",http_response_status_code="503",le="10000",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
-http_server_response_body_size_bytes{http_request_method="GET",http_response_status_code="503",le="25",network_protocol_name="http",network_protocol_version="1.1",otel_scope_name="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp",otel_scope_schema_url="",otel_scope_version="0.63.0",server_address="localhost",server_port="13133",url_scheme="http"}
...

➡️ View full metrics file

yurishkuro · 2025-12-06T04:31:20Z

@copilot see PR review comments and apply them

Copilot · 2025-12-06T04:35:20Z

@copilot see PR review comments and apply them

Applied all PR review suggestions. Removed sections per your code review:

Project Evolution section (v1 vs v2 explanation)
Version-specific labels in repository structure
macOS-Specific Setup section
Three Ways to Satisfy Coverage Requirements detailed examples
v1 vs v2 Architecture Insights section

Updated all remaining references to be version-neutral (changed "Jaeger v2" to "Jaeger" throughout).

The document is now more streamlined and focused on current practices without historical architecture distinctions.

Commit: ced76f2

Co-authored-by: yurishkuro <[email protected]>

- Add Quick Start section for first-time AI agents - Expand project overview with v1 vs v2 architecture context - Add detailed First-Time Setup with macOS-specific instructions - Document comprehensive development workflow and commit guidelines - Expand testing guidelines with 3 coverage requirement options - Add extensive Common Errors and Workarounds section (15+ errors) - Document common commands with practical examples - Add AI Agent Best Practices with code examples - Include Architecture Insights section explaining data model - Add Summary quick reference checklist The guide now totals 1248 lines (was 286) and provides: - Actual errors encountered and their solutions - Step-by-step troubleshooting for common issues - Code examples for proper patterns - Understanding of v1/v2 architecture coexistence - Storage backend considerations - OTel Collector integration patterns Addresses feedback to thoroughly document repository onboarding for AI coding agents seeing the codebase for the first time. Co-authored-by: yurishkuro <[email protected]>

- Clarify to prefer v2 patterns for new contributions - Adjust GNU sed description from "Required" to "Typically required" - Fix future date to December 2024 Co-authored-by: yurishkuro <[email protected]>

Signed-off-by: Yuri Shkuro <[email protected]>

Remove sections per code review: - Remove "Project Evolution" section explaining v1 vs v2 architecture - Simplify repository structure removing v1/v2 labels - Remove "macOS-Specific Setup" section - Remove "Three Ways to Satisfy Coverage Requirements" detailed examples - Update remaining v2 references to be version-neutral - Remove v1 vs v2 Architecture Insights section These simplifications make the document more focused on current practices without confusing readers about historical architecture decisions. Co-authored-by: yurishkuro <[email protected]>

Signed-off-by: Yuri Shkuro <[email protected]>

scripts/makefiles/BuildBinaries.mk

Signed-off-by: Yuri Shkuro <[email protected]> Signed-off-by: Yuri Shkuro <[email protected]> Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: yurishkuro <[email protected]> Co-authored-by: Yuri Shkuro <[email protected]> Co-authored-by: Yuri Shkuro <[email protected]>

jkowall · 2025-12-06T19:08:20Z

@yurishkuro not sure which model you used for this, but I like to cross reference other models for things like prompts. I ran the AGENTS.md through Gemini pro and got this feedback on enhancements

Based on your focus on monitoring, observability, and the current architectural shift of Jaeger towards the OpenTelemetry Collector (v2), here is a significantly enhanced AGENTS.md.

This version provides AI agents with the necessary context regarding the v2 architecture, self-observability standards (how to write code that monitors itself), and integration testing nuances.

Enhanced `AGENTS.md`

# AGENTS.md

## Context & Architecture
Jaeger is a distributed tracing platform. The project is currently transitioning to **Jaeger v2**, which is built as a distribution of the **OpenTelemetry (OTel) Collector**.

### V1 vs. V2
- **Legacy (v1):** Monolithic binaries (Collector, Query, Agent) using internal frameworks.
- **Current (v2):** Built on top of the OpenTelemetry Collector framework.
    - **Receivers:** Ingest trace data (replacing Jaeger Collectors).
    - **Processors:** Transform or batch data.
    - **Exporters:** Send data to storage backends (Cassandra, Elasticsearch, ClickHouse, etc.).
    - **Extensions:** Provide management capabilities.

**Guideline:** When modifying `cmd/jaeger`, assume OTel Collector architecture conventions (Component lifecycle, configuration via OTEL factories).

## Project Structure
- `cmd/`: Main applications.
    - `jaeger/`: **(Primary)** The Jaeger v2 binary (OTel Collector distro).
    - `anonymizer/`: Trace anonymization tool.
    - `es-index-cleaner/`: Maintenance tool for Elasticsearch.
- `internal/`: Private library code.
    - `storage/`: Storage backend implementations (v1/v2 shared logic).
    - `metricstest/`: Utilities for asserting metric values in tests.
- `pkg/`: Shared libraries importable by other projects.
    - `config/`: Viper/Flag configuration utilities.
    - `metrics/`: Internal metrics abstraction layer (adapters for Prometheus/OTel).
- `jaeger-ui/`: Submodule for the frontend assets.
- `idl/`: Data models (Protobuf, Thrift).
- `docker-compose/`: Infrastructure definitions for integration testing.

## Development Workflow

### Setup
Initialize the environment and submodules:
```bash
git submodule update --init --recursive
make install-tools

Build Targets

V2 Binary: make build-jaeger-v2 (or make build-binaries)
Docker Images: make build-images

Testing & Verification

Unit Tests: make test
- Note: This runs standard Go tests.
Integration Tests: make storage-integration-test
- Requirement: Requires Docker to be running. These tests spin up actual storage backends (Cassandra, ES) to verify internal/storage implementations.
Linting: make lint
- Auto-fix: If linting fails on formatting/imports, run make fmt.

Coding Standards: Observability & Monitoring

Jaeger must be observable. Code changes should prioritize self-monitoring (metrics) and logging.

1. Logging

Library: Use go.uber.org/zap.
Level:
- Info: Startup/shutdown events, configuration changes.
- Error: Actionable failures (IO errors, connection loss).
- Debug: High-volume per-request details (disabled by default).
Structure: Always use structured logging fields, not fmt.Sprintf.
- Bad: logger.Error("failed to connect to " + host)
- Good: logger.Error("failed to connect", zap.String("host", host), zap.Error(err))

2. Metrics (Self-Observability)

Library: Use the internal pkg/metrics abstraction or OTel SDKs directly where applicable in v2 components.
Naming Convention: Use snake_case.
Cardinality: Strictly avoid high-cardinality tags (e.g., do not use trace_id or error_message as a metric tag).
Golden Signals: Ensure new components emit metrics for:
- Latency: Histogram of operation duration.
- Traffic: Counter of requests/events received.
- Errors: Counter of failed operations.

3. Tracing (Internal)

Use go.opentelemetry.io/otel to trace internal Jaeger operations.
Propagate context.Context in all functions to ensure trace continuity.

Implementation Guidelines

Configuration: Use viper for v1 components and OTel's confmap for v2 components.
Error Handling: Use fmt.Errorf("%w", err) to wrap errors for stack unwinding.
Concurrency: Prefer channels and sync.WaitGroup. Avoid raw mutexes unless performance critical.

Do Not Edit

These files are auto-generated. Modifications here will be overwritten:

*.pb.go
*_mock.go (generated by mockery)
internal/proto-gen/
swagger/

Before Submitting

Run make fmt to ensure license headers and imports are correct.
Run make lint to check for static analysis errors.
If modifying storage, run the specific integration test (e.g., make test-cassandra).


### Key Changes Explained

1.  **Architecture Section:** I added a "Context" section that explicitly mentions the shift to **Jaeger v2** and the **OpenTelemetry Collector**. This is critical because an agent might otherwise suggest legacy v1 patterns (like the old Agent/Collector split) that are being phased out.
2.  **Observability & Monitoring Section:** This responds directly to your request. It gives the agent specific rules on:
    * **Logging:** Enforcing structured logging (`zap`) helps downstream log aggregators.
    * **Metrics:** Warning against high cardinality is vital for performance. It instructs the agent to implement "Golden Signals" (Latency, Traffic, Errors) for any new feature.
    * **Internal Tracing:** Ensures `context.Context` propagation so Jaeger can trace itself.
3.  **Refined Project Structure:** I highlighted `cmd/jaeger` as the primary v2 binary and explained the purpose of `internal/storage` versus `pkg/`, which helps the agent place code in the correct directory.
4.  **Integration Testing:** I clarified that `make test` is usually just unit tests, whereas storage changes require `make storage-integration-test` and a Docker environment.

Would you like me to generate a specific rule set for the `golangci-lint` configuration to enforce the logging standards mentioned above?

Grok Heavy suggests other changes, good ones for CI/CD

--- original.md
+++ enhanced.md
@@ -1,17 +1,35 @@
 # AGENTS.md
 
 ## Overview
-This file provides context and instructions for AI agents working on the Jaeger repository. Jaeger is a distributed tracing platform.
+This file provides context and instructions for AI agents working on the Jaeger repository. Jaeger is a distributed tracing platform originally inspired by Dapper and Zipkin, now integrated with OpenTelemetry for end-to-end distributed tracing, monitoring, and troubleshooting of complex microservices architectures.
+
+### Key Features
+- Supports multiple storage backends (e.g., Cassandra, Elasticsearch, Badger, Kafka).
+- Includes components like Collector, Query Service, Ingester, and Agent.
+- Frontend built with React for visualization of traces.
+- Emphasis on scalability, reliability, and integration with modern observability stacks.
 
 ## Project Structure
 - `cmd/`: Main applications and binaries.
     - `jaeger/`: The main Jaeger v2 binary based on the OpenTelemetry Collector.
-    - Other tools and utilities.
+    - `agent/`: The Jaeger Agent for receiving spans from instrumented applications.
+    - `collector/`: The Jaeger Collector for processing and storing spans.
+    - `query/`: The Query service for retrieving traces.
+    - `ingester/`: Kafka-based ingester for high-throughput scenarios.
+    - Other tools and utilities like `all-in-one` for local development.
 - `internal/`: Private library code.
-    - `storage/`: Various implementations of storage backends.
-- `jaeger-ui/`: Submodule for the frontend (React).
-- `idl/`: Submodule for data models (Protobuf, Thrift).
-- `scripts/`: Build and maintenance scripts.
+    - `storage/`: Various implementations of storage backends (e.g., `badger/`, `cassandra/`, `elasticsearch/`).
+    - `metrics/`: Metrics handling and Prometheus integration.
+    - `trace/`: Core tracing logic and span processing.
+- `jaeger-ui/`: Submodule for the frontend (React-based UI for trace visualization).
+- `idl/`: Submodule for data models (Protobuf, Thrift definitions for spans and dependencies).
+- `scripts/`: Build and maintenance scripts (e.g., for Docker, CI, and code generation).
+- `pkg/`: Public library code reusable outside the project.
+- `examples/`: Sample applications and configurations for testing Jaeger integrations.
+- `docker/`: Dockerfiles for building container images.
+- `api_v2/`: API definitions and handlers for Jaeger Query API.
+
+**Note for Agents**: When analyzing code, prioritize understanding dependencies between components (e.g., how the Collector interacts with storage backends). Use tools like `go mod graph` to visualize module dependencies.
 
 ## Development Workflow
 
@@ -21,23 +39,63 @@
 git submodule update --init --recursive
 make install-tools

+- Install Go (version 1.21+ recommended, as per go.mod).
+- For UI development: Navigate to jaeger-ui/ and run yarn install.
+- Set up storage backends for local testing (e.g., run Cassandra or Elasticsearch via Docker: docker-compose up from docker/).

Build

Binaries: make build-binaries or specific targets like make build-jaeger.
+- UI: make build-ui to build the React frontend.
+- All-in-One: make build-all-in-one for a quick local setup.
+- Cross-Platform: Use make build-platforms for multi-architecture builds.
+- Docker Images: make docker to build images for deployment.

+Tip: Use make help to list all available targets.

Test

-- Unit Tests: make test matches standard go test but includes tags for specific storages.
-- Lint: make lint runs golangci-lint and other checks.
-- Format: make fmt runs gofumpt and updates license headers. Note: Run this before submitting changes.
+- Unit Tests: make test runs go test with tags for specific storages (e.g., make test TAG=elasticsearch).
+- Integration Tests: make integration-test for end-to-end scenarios.
+- UI Tests: In jaeger-ui/, run yarn test.
+- Benchmarking: make benchmark for performance tests on critical paths like span ingestion.
+- Lint: make lint runs golangci-lint and other checks (e.g., license headers, YAML validation).
+- Format: make fmt runs gofumpt and updates license headers. Note: Run this before submitting changes to avoid CI failures.
+
+Coverage: Aim for >80% coverage on new code. Use make cover to generate reports.
+
+### Debugging and Running Locally
+- Run All-in-One: ./cmd/all-in-one/all-in-one (after build) for a local instance with in-memory storage.
+- With Storage: Configure via environment variables (e.g., SPAN_STORAGE_TYPE=elasticsearch).
+- Debugging: Use Delve (dlv debug ./cmd/jaeger) or attach to running processes.
+- Hot Reloading for UI: In jaeger-ui/, run yarn start and proxy to backend.
+
+### Dependency Management
+- Use Go Modules: go mod tidy to update dependencies.
+- Vendoring: make vendor to vendor dependencies for reproducible builds.
+- Avoid introducing new dependencies without justification; prefer standard library or existing ones.
+
+### CI/CD
+- GitHub Actions: Workflows in .github/workflows/ handle build, test, lint, and release.
+- Triggered on PRs and pushes to main.
+- For agents: Simulate CI locally with act tool if needed for validation.

Agent Guidelines

-- Testing: Always run make test after changes.
-- Linting: If make lint fails, try make fmt to fix formatting issues automatically.
-- Submodules: Be aware that jaeger-ui and idl are submodules. Modifications there might require PRs to their respective repositories.
-- Context: Refer to CONTRIBUTING.md for human-centric guidelines like DCO signing and PR etiquette.
+- Testing: Always run make test and make integration-test after changes. Validate against multiple storage backends if applicable.
+- Linting: If make lint fails, try make fmt to fix formatting issues automatically. Address all linter warnings.
+- Submodules: Be aware that jaeger-ui and idl are submodules. Modifications there might require PRs to their respective repositories (e.g., jaegertracing/jaeger-ui).
+- Context: Refer to CONTRIBUTING.md for human-centric guidelines like DCO signing, PR etiquette, and commit message formats (e.g., "fix(storage): resolve issue with Badger indexing").
+- Coding Standards: Follow Go best practices – use meaningful variable names, add comments for complex logic, adhere to error handling patterns (e.g., wrap errors with fmt.Errorf). Prefer interfaces for extensibility (e.g., storage plugins).
+- Security: Scan for vulnerabilities with make scan. Avoid hardcoding secrets; use config files or env vars.
+- Performance: Profile changes with pprof if impacting high-throughput areas like Collector.
+- Documentation: Update README.md or component docs (e.g., in cmd/) for new features. Use Markdown tables for config options.
+- OpenTelemetry Integration: Ensure compatibility with OTel Collector contrib. Test with latest OTel SDKs.
+- AI-Specific Tips: When suggesting changes, provide diff snippets. Analyze issues by searching GitHub issues/PRs first. Prioritize backward compatibility.

Do Not Edit

The following files are auto-generated. Do not edit them manually:

*.pb.go
*_mock.go
internal/proto-gen/
+- api_v2/*.pb.go (from Protobuf)
+- Files in vendor/ (regenerate with make vendor)

+Regeneration: Use make proto for Protobuf files or make generate for mocks and other generated code.

yurishkuro · 2025-12-06T20:36:12Z

@jkowall I tried several. I started w/ GH Copilot, and it created 10 pages of nonsense, like explaining how to do data driven tests. The one I settled on is by Antigravity (Gemini 3 Pro). I even specifically asked it to compare its version with Copilot's and I agree with its critique:

I've analyzed the AGENTS.md from the PR. The difference comes down to philosophy and your specific constraints.

The Copilot version creates a comprehensive context dump. It copies vast amounts of information from CONTRIBUTING.md, the Makefile, and architectural docs into one place.

Pros: "One-stop shop" for an agent that might not look elsewhere.
Cons: High maintenance (data rot), wastes token context with redundant info, and violates the "single source of truth" principle.
My version respects your constraint: "Avoid duplicating instructions that are already present in CONTRIBUTING.md".

Design: It acts as a map for the agent, pointing to where the actual truth lives (e.g., "Read CONTRIBUTING.md for workflow," "Check Makefile for commands").
Benefit: It's lightweight, doesn't go stale as easily, and assumes the agent is smart enough to read referenced files (like CONTRIBUTING.md) when needed.

jkowall · 2025-12-06T20:40:31Z

Thanks for the details. How is the test coverage? That seems like something we could specify better in the file.

yurishkuro · 2025-12-06T21:09:26Z

yes, that can be added, Copilot's version had it.

Copilot AI assigned Copilot and yurishkuro Dec 5, 2025

Copilot started work on behalf of yurishkuro December 5, 2025 16:08 View session

Copilot AI changed the title ~~[WIP] Create AGENTS.md documentation for repository~~ Add AGENTS.md for AI coding assistant guidance Dec 5, 2025

Copilot AI requested a review from yurishkuro December 5, 2025 16:15

Copilot finished work on behalf of yurishkuro December 5, 2025 16:15

Copilot stopped work on behalf of yurishkuro due to an error December 6, 2025 02:52
Copilot has encountered an error. See logs for additional details.

Copilot started work on behalf of yurishkuro December 6, 2025 02:54 View session

Copilot AI changed the title ~~Add AGENTS.md for AI coding assistant guidance~~ Add comprehensive AGENTS.md for AI coding assistant onboarding Dec 6, 2025

Copilot finished work on behalf of yurishkuro December 6, 2025 03:04