"""OTel metric instruments for <agent-name>.

All metrics flow through the global MeterProvider installed by the OTel
Operator's init container. The provider exports OTLP to the cluster tier-1
collector, which forwards metrics to Prometheus via tier-2's remote-write.

Naming convention (see SPEC §7.4):

    agent.<agent_type>.<noun>            — counters (unit="1")
    agent.<agent_type>.<noun>.duration   — histograms in seconds (unit="s")

Replace `<agent_name>` and the example instruments with your own.
"""
from __future__ import annotations

from opentelemetry import metrics

# The (name, version) pair becomes `otel_scope_name` and `otel_scope_version`
# attributes on every metric — useful for filtering in PromQL.
_meter = metrics.get_meter("<agent-name>", "0.1.0")

# ─── Example: an "echo" operation counter and latency histogram ─────────
echoes = _meter.create_counter(
    "agent.<agent_name>.echoes",
    unit="1",
    description="Echo requests by outcome.",
)

echo_duration = _meter.create_histogram(
    "agent.<agent_name>.echo.duration",
    unit="s",
    description="End-to-end /echo latency.",
)