agentirc-cli 8.3.0__tar.gz → 8.4.0__tar.gz

{agentirc_cli-8.3.0 → agentirc_cli-8.4.0}/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this project will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [8.4.0] - 2026-04-25
+
+### Added
+
+- `culture/telemetry/metrics.py`: `init_metrics(config)` + `MetricsRegistry` dataclass for all 15 server-side instruments — mirrors `tracing.py`'s idempotency + no-op pattern.
+- Public `culture.telemetry.MetricsRegistry` and `culture.telemetry.init_metrics`.
+- `TelemetryConfig.metrics_enabled` (default `True`) and `metrics_export_interval_ms` (default 10000).
+- Message-flow metrics: `culture.irc.bytes_sent`, `culture.irc.bytes_received`, `culture.irc.message.size`, `culture.privmsg.delivered`.
+- Events metrics: `culture.events.emitted`, `culture.events.render.duration`.
+- Federation metrics: `culture.s2s.messages` (inbound), `culture.s2s.relay_latency`, `culture.s2s.links_active`, `culture.s2s.link_events`.
+- Client metrics: `culture.clients.connected`, `culture.client.session.duration`, `culture.client.command.duration`.
+- `culture.trace.inbound` counter — closes Plan 2's deferral.
+- `tests/conftest.py` `metrics_reader` fixture parallel to `tracing_exporter`.
+- `tests/telemetry/_metrics_helpers.py` — `get_counter_value`, `get_histogram_count`, `get_up_down_value`.
+
 ## [8.3.0] - 2026-04-25
 
 ### Added

{agentirc_cli-8.3.0 → agentirc_cli-8.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 8.3.0
+Version: 8.4.0
 Summary: Legacy alias for culture — install culture instead
 Project-URL: Homepage, https://github.com/OriNachum/culture
 Author: Ori Nachum

{agentirc_cli-8.3.0 → agentirc_cli-8.4.0}/culture/agentirc/client.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 import asyncio
 import logging
 import re
+import time
 from typing import TYPE_CHECKING
 
 from opentelemetry import trace as _otel_trace
@@ -77,8 +78,12 @@ class Client:
             if tp is not None:
                 _inject_traceparent(message, traceparent=tp, tracestate=None)
         try:
-            self.writer.write(message.format().encode("utf-8"))
+            wire = message.format().encode("utf-8")
+            self.writer.write(wire)
             await self.writer.drain()
+            # Record bytes after a successful drain so we don't count
+            # writes that immediately faulted.
+            self.server.metrics.irc_bytes_sent.add(len(wire), {"direction": "s2c"})
         except OSError:
             pass  # Client disconnected; cleanup happens in ircd._handle_connection
 
@@ -96,8 +101,10 @@ class Client:
                 # block; prefix a fresh @tag.
                 line = f"@{_TP_TAG_NAME}={tp} {line}"
         try:
-            self.writer.write(f"{line}\r\n".encode("utf-8"))
+            wire = f"{line}\r\n".encode("utf-8")
+            self.writer.write(wire)
             await self.writer.drain()
+            self.server.metrics.irc_bytes_sent.add(len(wire), {"direction": "s2c"})
         except OSError:
             pass  # Client disconnected; cleanup happens in ircd._handle_connection
 
@@ -142,6 +149,13 @@ class Client:
                         },
                     )
                     continue
+                # Record received bytes + message size for every successfully-parsed
+                # line.  +2 accounts for the \r\n that was stripped during line-split.
+                line_bytes = len(line.encode("utf-8")) + 2
+                self.server.metrics.irc_bytes_received.add(line_bytes, {"direction": "c2s"})
+                self.server.metrics.irc_message_size.record(
+                    line_bytes, {"verb": msg.command, "direction": "c2s"}
+                )
                 if msg.command:
                     await self._dispatch(msg)
             return buffer
@@ -149,6 +163,9 @@ class Client:
     async def handle(self, initial_msg: str | None = None) -> None:
         peer_info = self.writer.get_extra_info("peername")
         remote_addr = f"{peer_info[0]}:{peer_info[1]}" if peer_info else ""
+        kind = "human"  # Plan 5/6 will refine to bot/harness
+        self.server.metrics.clients_connected.add(1, {"kind": kind})
+        session_started = time.perf_counter()
         with _otel_trace.get_tracer(_TRACER_NAME).start_as_current_span(
             "irc.client.session",
             attributes={"irc.client.remote_addr": remote_addr},
@@ -172,9 +189,15 @@ class Client:
                     buffer = await self._process_buffer(buffer)
             except (ConnectionError, asyncio.IncompleteReadError):
                 pass
+            finally:
+                self.server.metrics.clients_connected.add(-1, {"kind": kind})
+                self.server.metrics.client_session_duration.record(
+                    time.perf_counter() - session_started, {"kind": kind}
+                )
 
     async def _dispatch(self, msg: Message) -> None:
         extract = extract_traceparent_from_tags(msg, peer=None)
+        self.server.metrics.trace_inbound.add(1, {"result": extract.status, "peer": ""})
         if extract.status == "valid":
             parent_ctx: _OtelContext | None = context_from_traceparent(extract.traceparent)
         else:
@@ -190,6 +213,7 @@ class Client:
             attrs["culture.trace.dropped_reason"] = extract.status
 
         # Per-call get_tracer: test fixture swaps provider between tests.
+        cmd_started = time.perf_counter()
         with _otel_trace.get_tracer(_TRACER_NAME).start_as_current_span(
             f"irc.command.{verb}",
             context=parent_ctx,
@@ -211,6 +235,9 @@ class Client:
                     await self.send_numeric(
                         replies.ERR_UNKNOWNCOMMAND, msg.command, "Unknown command"
                     )
+        self.server.metrics.client_command_duration.record(
+            (time.perf_counter() - cmd_started) * 1000.0, {"verb": verb}
+        )
 
     async def _handle_ping(self, msg: Message) -> None:
         token = msg.params[0] if msg.params else ""
@@ -724,6 +751,7 @@ class Client:
             for member in list(channel.members):
                 if member is not self:
                     await member.send(relay)
+            self.server.metrics.privmsg_delivered.add(1, {"kind": "channel", "channel": target})
             event_data = {"text": text}
             if is_notice:
                 event_data["notice"] = True
@@ -758,6 +786,7 @@ class Client:
                 )
             else:
                 await recipient.send(relay)
+            self.server.metrics.privmsg_delivered.add(1, {"kind": "dm"})
             event_data = {"text": text, "target": target}
             if is_notice:
                 event_data["notice"] = True

{agentirc_cli-8.3.0 → agentirc_cli-8.4.0}/culture/agentirc/config.py

@@ -24,6 +24,8 @@ class TelemetryConfig:
     otlp_compression: str = "gzip"  # gzip | none
     traces_enabled: bool = True
     traces_sampler: str = "parentbased_always_on"
+    metrics_enabled: bool = True
+    metrics_export_interval_ms: int = 10000
 
 
 @dataclass

{agentirc_cli-8.3.0 → agentirc_cli-8.4.0}/culture/agentirc/ircd.py

@@ -5,6 +5,7 @@ import asyncio
 import base64
 import json
 import logging
+import time
 from collections import deque
 from typing import TYPE_CHECKING
 
@@ -25,6 +26,9 @@ from culture.protocol.message import Message
 
 logger = logging.getLogger(__name__)
 
+# Span/metric attribute keys defined once so a future rename has one edit point.
+_ATTR_EVENT_TYPE = "event.type"
+
 if TYPE_CHECKING:
     from culture.agentirc.client import Client
     from culture.agentirc.remote_client import RemoteClient
@@ -35,10 +39,11 @@ class IRCd:
     """The culture IRC server."""
 
     def __init__(self, config: ServerConfig):
-        from culture.telemetry import init_telemetry
+        from culture.telemetry import init_metrics, init_telemetry
 
         self.config = config
         self.tracer = init_telemetry(config)
+        self.metrics = init_metrics(config)
         self.clients: dict[str, Client | VirtualClient] = {}  # nick -> Client
         self.channels: dict[str, Channel] = {}  # name -> Channel
         self.skills: list[Skill] = []
@@ -178,7 +183,7 @@ class IRCd:
         # server_link.py).
         event_type_str = event.type.value if hasattr(event.type, "value") else str(event.type)
         attrs: dict[str, str] = {
-            "event.type": event_type_str,
+            _ATTR_EVENT_TYPE: event_type_str,
             "event.origin": "federated" if origin_tag else "local",
         }
         if event.channel:
@@ -212,6 +217,12 @@ class IRCd:
     async def emit_event(self, event: Event) -> None:
         origin_tag = event.data.get("_origin")
         attrs = self._build_event_span_attrs(event, origin_tag)
+        event_type_str = attrs[_ATTR_EVENT_TYPE]
+        origin_str = "federated" if origin_tag else "local"
+
+        self.metrics.events_emitted.add(1, {_ATTR_EVENT_TYPE: event_type_str, "origin": origin_str})
+        render_started = time.perf_counter()
+
         # Per-call get_tracer: the `tracing_exporter` test fixture swaps the
         # global provider between tests; a cached Tracer would bind to the
         # first test's provider and stop delivering to later ones.
@@ -226,6 +237,9 @@ class IRCd:
             await self._dispatch_to_bots(event)
             await self._surface_event_privmsg(event)
 
+        render_ms = (time.perf_counter() - render_started) * 1000.0
+        self.metrics.events_render_duration.record(render_ms, {_ATTR_EVENT_TYPE: event_type_str})
+
     _NO_SURFACE_TYPES = NO_SURFACE_EVENT_TYPES
 
     @staticmethod

{agentirc_cli-8.3.0 → agentirc_cli-8.4.0}/culture/agentirc/server_link.py

@@ -5,6 +5,7 @@ import asyncio
 import base64
 import json
 import logging
+import time
 from typing import TYPE_CHECKING
 
 from opentelemetry import trace as otel_trace
@@ -137,8 +138,11 @@ class ServerLink:
             except Exception:  # noqa: BLE001 - telemetry must never break the link
                 logger.debug("traceparent injection failed; sending untagged", exc_info=True)
         try:
-            self.writer.write(f"{line}\r\n".encode("utf-8"))
+            wire = f"{line}\r\n".encode("utf-8")
+            self.writer.write(wire)
             await self.writer.drain()
+            if self.server is not None:
+                self.server.metrics.irc_bytes_sent.add(len(wire), {"direction": "s2s"})
         except OSError:
             pass
 
@@ -155,6 +159,13 @@ class ServerLink:
             line, buffer = buffer.split("\n", 1)
             if line.strip():
                 msg = Message.parse(line)
+                if self.server is not None:
+                    # +2 accounts for the \r\n that was stripped during line-split.
+                    line_bytes = len(line.encode("utf-8")) + 2
+                    self.server.metrics.irc_bytes_received.add(line_bytes, {"direction": "s2s"})
+                    self.server.metrics.irc_message_size.record(
+                        line_bytes, {"verb": msg.command, "direction": "s2s"}
+                    )
                 if msg.command:
                     await self._dispatch(msg)
         return buffer
@@ -187,6 +198,14 @@ class ServerLink:
             except (ConnectionError, asyncio.IncompleteReadError):
                 pass
             finally:
+                if self._authenticated:
+                    direction = "outbound" if self.initiator else "inbound"
+                    self.server.metrics.s2s_links_active.add(
+                        -1, {"peer": self.peer_name or "", "direction": direction}
+                    )
+                    self.server.metrics.s2s_link_events.add(
+                        1, {"peer": self.peer_name or "", "event": "disconnect"}
+                    )
                 await self.server._remove_link(self, squit=self._squit_received)
                 self.writer.close()
                 try:
@@ -203,11 +222,20 @@ class ServerLink:
         handler = getattr(self, f"_handle_{msg.command.lower()}", None)
 
         extracted = extract_traceparent_from_tags(msg, peer=self.peer_name)
+        self.server.metrics.trace_inbound.add(
+            1, {"result": extracted.status, "peer": self.peer_name or ""}
+        )
         if extracted.status == "valid":
             parent_ctx: _OtelContext | None = context_from_traceparent(extracted.traceparent)
         else:
             parent_ctx = _OtelContext()  # force root: detach from session span
 
+        if self.server is not None:
+            self.server.metrics.s2s_messages.add(
+                1,
+                {"verb": verb, "direction": "inbound", "peer": self.peer_name or ""},
+            )
+
         attrs = {
             "irc.command": verb,
             "culture.trace.origin": "remote",
@@ -266,17 +294,26 @@ class ServerLink:
         """
         if self._peer_pass != self.password:
             logger.warning("Bad password from peer %s", self.peer_name)
+            self.server.metrics.s2s_link_events.add(
+                1, {"peer": self.peer_name or "", "event": "auth_fail"}
+            )
             await self.send_raw("ERROR :Bad password")
             raise ConnectionError("Bad S2S password")
 
         # Check for duplicate server name
         if self.peer_name in self.server.links:
             logger.warning("Duplicate server name %s", self.peer_name)
+            self.server.metrics.s2s_link_events.add(
+                1, {"peer": self.peer_name or "", "event": "auth_fail"}
+            )
             await self.send_raw(f"ERROR :Server name {self.peer_name} already linked")
             raise ConnectionError("Duplicate server name")
 
         if self.peer_name == self.server.config.name:
             logger.warning("Peer has same name as us: %s", self.peer_name)
+            self.server.metrics.s2s_link_events.add(
+                1, {"peer": self.peer_name or "", "event": "auth_fail"}
+            )
             await self.send_raw("ERROR :Cannot link to self")
             raise ConnectionError("Cannot link to self")
 
@@ -291,6 +328,11 @@ class ServerLink:
         await self._validate_peer_credentials()
 
         self._authenticated = True
+        direction = "outbound" if self.initiator else "inbound"
+        self.server.metrics.s2s_links_active.add(
+            1, {"peer": self.peer_name, "direction": direction}
+        )
+        self.server.metrics.s2s_link_events.add(1, {"peer": self.peer_name, "event": "connect"})
         if self._session_span is not None:
             self._session_span.set_attribute("s2s.peer", self.peer_name)
         self.server.links[self.peer_name] = self
@@ -900,6 +942,10 @@ class ServerLink:
         except ValueError:
             return
 
+        self.server.metrics.s2s_link_events.add(
+            1, {"peer": self.peer_name or "", "event": "backfill_start"}
+        )
+
         # Use the higher of: what peer claims, or what we know they acked
         # (during real-time relay, peer saw everything up to our _seq at link drop)
         acked = self.server._peer_acked_seq.get(self.peer_name, 0)
@@ -910,6 +956,9 @@ class ServerLink:
                 await self._replay_event(seq, event)
 
         await self.send_raw(f":{self.server.config.name} BACKFILLEND {self.server._seq}")
+        self.server.metrics.s2s_link_events.add(
+            1, {"peer": self.peer_name or "", "event": "backfill_complete"}
+        )
 
     def _handle_backfillend(self, msg: Message) -> None:
         """Peer finished backfilling."""
@@ -946,6 +995,8 @@ class ServerLink:
             "event.type": event_type_str,
             "s2s.peer": self.peer_name or "",
         }
+        relay_started = time.perf_counter()
+        relayed = False
         # Single span name (no verb suffix): the wire verb is decided downstream
         # by _RELAY_DISPATCH or the SEVENT fallback, after this span opens.
         with otel_trace.get_tracer(_TRACER_NAME).start_as_current_span(
@@ -955,19 +1006,29 @@ class ServerLink:
             handler = self._RELAY_DISPATCH.get(event.type)
             if handler:
                 await maybe_await(handler(self, event, origin))
-                return
-
-            # If no typed relay exists, fall back to generic SEVENT.
-            # v1 assumes all peers support SEVENT; cap negotiation is deferred — see plan task 12.
-            payload = self.server._build_event_payload(event)
-            encoded = self.server._encode_event_data(payload, event_type_str)
-            target = event.channel or "*"
-            # Egress trust check: channel-scoped events respect should_relay; global events always relay
-            if event.channel is not None and not self.should_relay(event.channel):
-                return
-            seq = self.server._seq  # current local seq; peer stores but doesn't re-sequence
-            await self.send_raw(
-                f":{origin} SEVENT {origin} {seq} {event_type_str} {target} :{encoded}"
+                # v1: typed _relay_* handlers may early-return on internal trust checks
+                # without signaling. We optimistically count typed dispatch as relayed.
+                # Future: refactor _relay_* to return bool so latency only fires on
+                # genuine sends.
+                relayed = True
+            else:
+                # If no typed relay exists, fall back to generic SEVENT.
+                # v1 assumes all peers support SEVENT; cap negotiation is deferred — see plan task 12.
+                payload = self.server._build_event_payload(event)
+                encoded = self.server._encode_event_data(payload, event_type_str)
+                target = event.channel or "*"
+                # Egress trust check: channel-scoped events respect should_relay; global events always relay
+                if event.channel is None or self.should_relay(event.channel):
+                    seq = self.server._seq  # current local seq; peer stores but doesn't re-sequence
+                    await self.send_raw(
+                        f":{origin} SEVENT {origin} {seq} {event_type_str} {target} :{encoded}"
+                    )
+                    relayed = True
+
+        if relayed:
+            self.server.metrics.s2s_relay_latency.record(
+                (time.perf_counter() - relay_started) * 1000.0,
+                {"event.type": event_type_str, "peer": self.peer_name or ""},
             )
 
     async def _relay_message(self, event: Event, origin: str) -> None:

{agentirc_cli-8.3.0 → agentirc_cli-8.4.0}/culture/protocol/extensions/tracing.md

@@ -11,7 +11,7 @@
 
 1. Tag absent → start a new root span. Attribute: `culture.trace.origin=local`.
 2. Tag present and valid → start a child span linked to the extracted context. Attributes: `culture.trace.origin=remote`, `culture.federation.peer=<peer>`.
-3. Tag present but malformed or over the length cap → drop the tag, start a new root span. Attributes: `culture.trace.origin=remote`, `culture.trace.dropped_reason=malformed|too_long`, `culture.federation.peer=<peer>`. Log a rate-limited warning. Increment `culture.trace.inbound{result=malformed|too_long, peer=<peer>}`.
+3. Tag present but malformed or over the length cap → drop the tag, start a new root span. Attributes: `culture.trace.origin=remote`, `culture.trace.dropped_reason=malformed|too_long`, `culture.federation.peer=<peer>`. Log a rate-limited warning. Increment `culture.trace.inbound{result=malformed|too_long, peer=<peer>}` (shipped in culture 8.4.0; on every inbound regardless of result, so `result=valid` and `result=missing` are also recorded).
 
 **Length caps** (hard-coded, not configurable):
 

{agentirc_cli-8.3.0 → agentirc_cli-8.4.0}/culture/telemetry/__init__.py

@@ -12,15 +12,18 @@ from culture.telemetry.context import (
     extract_traceparent_from_tags,
     inject_traceparent,
 )
+from culture.telemetry.metrics import MetricsRegistry, init_metrics
 from culture.telemetry.tracing import init_telemetry
 
 __all__ = [
     "ExtractResult",
+    "MetricsRegistry",
     "TRACEPARENT_TAG",
     "TRACESTATE_TAG",
     "context_from_traceparent",
     "current_traceparent",
     "extract_traceparent_from_tags",
+    "init_metrics",
     "init_telemetry",
     "inject_traceparent",
 ]

agentirc_cli-8.4.0/culture/telemetry/metrics.py

@@ -0,0 +1,225 @@
+"""OpenTelemetry MeterProvider bootstrap for Culture.
+
+`init_metrics(config)` is idempotent — safe to call from multiple places.
+When `config.telemetry.enabled` or `metrics_enabled` is False, returns a
+MetricsRegistry whose instruments are bound to OTEL's proxy meter that
+becomes a real meter only if a provider is later installed. In production
+this is effectively no-op (no provider is installed). In tests, callers
+MUST `reset_for_tests()` between disabled-init and the `metrics_reader`
+fixture, otherwise the cached proxy instruments would forward to the
+freshly-installed test provider.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import asdict, dataclass
+
+from opentelemetry import metrics
+from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter
+from opentelemetry.metrics import Counter, Histogram, Meter, UpDownCounter
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
+from opentelemetry.sdk.resources import Resource
+
+from culture.agentirc.config import ServerConfig
+
+logger = logging.getLogger(__name__)
+
+_CULTURE_METER_NAME = "culture.agentirc"
+_initialized_for: dict | None = None
+_meter_provider: "MeterProvider | None" = None
+_registry: "MetricsRegistry | None" = None
+
+
+@dataclass
+class MetricsRegistry:
+    """All Plan-3 server-side instruments, registered once during init_metrics.
+
+    Plan 4/5/6 will extend by adding fields for audit / harness / bots.
+    Keep this a single dataclass and grow it — don't spawn parallel
+    registries per category.
+    """
+
+    # Message flow
+    irc_bytes_sent: Counter
+    irc_bytes_received: Counter
+    irc_message_size: Histogram
+    privmsg_delivered: Counter
+    # Events
+    events_emitted: Counter
+    events_render_duration: Histogram
+    # Federation
+    s2s_messages: Counter
+    s2s_relay_latency: Histogram
+    s2s_links_active: UpDownCounter
+    s2s_link_events: Counter
+    # Clients & sessions
+    clients_connected: UpDownCounter
+    client_session_duration: Histogram
+    client_command_duration: Histogram
+    # Trace-context hygiene
+    trace_inbound: Counter
+
+
+def reset_for_tests() -> None:
+    """Reset module state so each test gets a fresh provider. Test-only."""
+    global _initialized_for, _meter_provider, _registry
+    if _meter_provider is not None:
+        try:
+            _meter_provider.shutdown()
+        except Exception:  # noqa: BLE001
+            pass
+        _meter_provider = None
+    _initialized_for = None
+    _registry = None
+    # _METER_PROVIDER and Once live on the _internal sub-package, not the
+    # top-level metrics module (unlike the trace API which exposes them directly).
+    import opentelemetry.metrics._internal as _mi  # type: ignore[attr-defined]
+
+    _mi._METER_PROVIDER = None
+    _mi._METER_PROVIDER_SET_ONCE = _mi.Once()
+
+
+def _build_registry(meter: Meter) -> MetricsRegistry:
+    """Single source of truth for instrument names / units / descriptions.
+
+    Names and units must match docs/superpowers/specs/2026-04-24-otel-observability-design.md
+    Metrics catalog section.
+    """
+    return MetricsRegistry(
+        # Message flow
+        irc_bytes_sent=meter.create_counter(
+            "culture.irc.bytes_sent",
+            unit="By",
+            description="Bytes written to client/peer sockets",
+        ),
+        irc_bytes_received=meter.create_counter(
+            "culture.irc.bytes_received",
+            unit="By",
+            description="Bytes read from client/peer sockets",
+        ),
+        irc_message_size=meter.create_histogram(
+            "culture.irc.message.size",
+            unit="By",
+            description="Per-message byte size at parse time",
+        ),
+        privmsg_delivered=meter.create_counter(
+            "culture.privmsg.delivered",
+            description="Per-PRIVMSG delivery count, labeled by kind=dm|channel",
+        ),
+        # Events
+        events_emitted=meter.create_counter(
+            "culture.events.emitted",
+            description="Events through IRCd.emit_event, labeled by type and origin",
+        ),
+        events_render_duration=meter.create_histogram(
+            "culture.events.render.duration",
+            unit="ms",
+            description="Time spent in skill hooks + bot dispatch + surfacing",
+        ),
+        # Federation
+        s2s_messages=meter.create_counter(
+            "culture.s2s.messages",
+            description="Inbound S2S messages by verb and peer (outbound deferred)",
+        ),
+        s2s_relay_latency=meter.create_histogram(
+            "culture.s2s.relay_latency",
+            unit="ms",
+            description="Per-event relay duration in ServerLink.relay_event",
+        ),
+        s2s_links_active=meter.create_up_down_counter(
+            "culture.s2s.links_active",
+            description="Currently active federation links",
+        ),
+        s2s_link_events=meter.create_counter(
+            "culture.s2s.link_events",
+            description="Federation lifecycle events: connect/disconnect/auth_fail/backfill_*",
+        ),
+        # Clients & sessions
+        clients_connected=meter.create_up_down_counter(
+            "culture.clients.connected",
+            description="Currently connected clients by kind=human|bot|harness",
+        ),
+        client_session_duration=meter.create_histogram(
+            "culture.client.session.duration",
+            unit="s",
+            description="Per-client connection lifetime",
+        ),
+        client_command_duration=meter.create_histogram(
+            "culture.client.command.duration",
+            unit="ms",
+            description="Per-command dispatch duration by verb",
+        ),
+        # Trace-context hygiene
+        trace_inbound=meter.create_counter(
+            "culture.trace.inbound",
+            description="Inbound traceparent extraction outcome by result and peer",
+        ),
+    )
+
+
+def init_metrics(config: ServerConfig) -> MetricsRegistry:
+    """Initialize MeterProvider + register instruments. Idempotent.
+
+    Returns a MetricsRegistry. When telemetry is disabled or
+    metrics_enabled is False, instruments are bound to OTEL's proxy meter
+    — call sites can `instrument.add(...)` / `.record(...)` unconditionally
+    without guards. Production never installs a provider in this case.
+    """
+    global _initialized_for, _meter_provider, _registry
+
+    tcfg = config.telemetry
+    # Include config.name so two IRCd instances with identical TelemetryConfig
+    # but different names each get their own registry and correct
+    # service.instance.id resource attribute.
+    snapshot = {"telemetry": asdict(tcfg), "instance": config.name}
+    if _initialized_for == snapshot and _registry is not None:
+        return _registry
+
+    # Tear down the previous SDK provider before installing a new one.
+    # PeriodicExportingMetricReader spawns a background thread that needs an
+    # explicit shutdown call; otherwise tests leak workers and may double-export.
+    if _meter_provider is not None:
+        try:
+            _meter_provider.shutdown()
+        except Exception:  # noqa: BLE001 - shutdown errors must not crash init
+            logger.debug("MeterProvider shutdown failed", exc_info=True)
+        _meter_provider = None
+
+    if not tcfg.enabled or not tcfg.metrics_enabled:
+        meter = metrics.get_meter(_CULTURE_METER_NAME)
+        _registry = _build_registry(meter)
+        _initialized_for = snapshot
+        return _registry
+
+    resource = Resource.create(
+        {
+            "service.name": tcfg.service_name,
+            "service.instance.id": config.name,
+        }
+    )
+    exporter = OTLPMetricExporter(
+        endpoint=tcfg.otlp_endpoint,
+        timeout=tcfg.otlp_timeout_ms / 1000.0,
+        compression=(None if tcfg.otlp_compression == "none" else tcfg.otlp_compression),
+    )
+    reader = PeriodicExportingMetricReader(
+        exporter=exporter,
+        export_interval_millis=tcfg.metrics_export_interval_ms,
+    )
+    provider = MeterProvider(resource=resource, metric_readers=[reader])
+    metrics.set_meter_provider(provider)
+    _meter_provider = provider
+
+    meter = metrics.get_meter(_CULTURE_METER_NAME)
+    _registry = _build_registry(meter)
+    _initialized_for = snapshot
+    logger.info(
+        "OTEL metrics initialized: service=%s instance=%s endpoint=%s interval=%dms",
+        tcfg.service_name,
+        config.name,
+        tcfg.otlp_endpoint,
+        tcfg.metrics_export_interval_ms,
+    )
+    return _registry

{agentirc_cli-8.3.0 → agentirc_cli-8.4.0}/culture/telemetry/tracing.py

@@ -78,7 +78,10 @@ def init_telemetry(config: ServerConfig) -> Tracer:
     tcfg = config.telemetry
     # Compare against an immutable snapshot so in-place mutation of the
     # caller's TelemetryConfig is detected (the dataclass is not frozen).
-    snapshot = asdict(tcfg)
+    # Include config.name so two IRCd instances with identical TelemetryConfig
+    # but different names each get their own tracer and correct
+    # service.instance.id resource attribute. Mirrors metrics.py for parity.
+    snapshot = {"telemetry": asdict(tcfg), "instance": config.name}
     if _initialized_for == snapshot and _tracer is not None:
         return _tracer