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

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

@@ -4,6 +4,42 @@ 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
+
+- `irc.s2s.session` span over ServerLink connection lifetime.
+- `irc.s2s.<VERB>` per-verb spans on inbound federation messages with traceparent extraction and the inbound mitigation rules from `culture/protocol/extensions/tracing.md`.
+- `irc.s2s.relay` span on outbound relay enforcing the re-sign-per-hop rule.
+- `irc.client.session` span over Client connection lifetime (#290).
+- `irc.join` and `irc.part` spans (#290).
+- Public `culture.telemetry.context_from_traceparent` and `culture.telemetry.current_traceparent` helpers.
+- Single traceparent injection choke point at `ServerLink.send_raw`.
+- End-to-end propagation tests proving one `trace_id` spans federated client → server → relay → server hops.
+
+### Changed
+
+- `Client._dispatch` span name and `irc.command` attribute now uppercase, matching `ServerLink._dispatch` convention.
+
+### Fixed
+
+- `_replay_event` uses the hasattr-guarded comparison so string-typed federated `event.type` no longer skips the typed fast path. (#291)
+
 ## [8.2.0] - 2026-04-24
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 8.2.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.2.0 → agentirc_cli-8.4.0}/culture/agentirc/client.py

@@ -4,11 +4,12 @@ from __future__ import annotations
 import asyncio
 import logging
 import re
+import time
 from typing import TYPE_CHECKING
 
 from opentelemetry import trace as _otel_trace
-from opentelemetry.trace import NonRecordingSpan, SpanContext, TraceFlags
-from opentelemetry.trace.propagation import set_span_in_context
+from opentelemetry.context import Context as _OtelContext
+from opentelemetry.trace import Span as _OtelSpan
 
 from culture.agentirc.channel import Channel
 from culture.agentirc.skill import Event, EventType
@@ -18,6 +19,8 @@ from culture.protocol import replies
 from culture.protocol.message import Message
 from culture.telemetry.context import TRACEPARENT_TAG as _TP_TAG_NAME
 from culture.telemetry.context import (
+    context_from_traceparent,
+    current_traceparent,
     extract_traceparent_from_tags,
 )
 from culture.telemetry.context import inject_traceparent as _inject_traceparent
@@ -25,39 +28,12 @@ from culture.telemetry.context import inject_traceparent as _inject_traceparent
 # OTEL instrumentation name (must match `_CULTURE_TRACER_NAME` in
 # culture/telemetry/tracing.py so trace consumers see one consistent value).
 _TRACER_NAME = "culture.agentirc"
-# Span attribute keys for PRIVMSG body capture, defined once so a future
-# rename / sanitization layer has one edit point.
+# Span attribute keys, defined once so a future rename / sanitization layer
+# has one edit point.
 _ATTR_BODY = "irc.message.body"
 _ATTR_SIZE = "irc.message.size"
-
-
-def _context_from_traceparent(tp: str):
-    """Build an OTEL context whose current span is a NonRecordingSpan
-    synthesized from a W3C traceparent string. The `_dispatch` span we
-    start next will be a child of this context."""
-    # Format: 00-<trace-id>-<parent-id>-<flags>
-    _, trace_hex, parent_hex, flags_hex = tp.split("-")
-    span_ctx = SpanContext(
-        trace_id=int(trace_hex, 16),
-        span_id=int(parent_hex, 16),
-        is_remote=True,
-        trace_flags=TraceFlags(int(flags_hex, 16)),
-    )
-    return set_span_in_context(NonRecordingSpan(span_ctx))
-
-
-def _current_traceparent() -> str | None:
-    """Return the W3C traceparent for the currently-active span, or None
-    if no span is recording (no-op tracer / sampler dropped).
-    """
-    span = _otel_trace.get_current_span()
-    ctx = span.get_span_context()
-    if not ctx.is_valid:
-        return None
-    return (
-        f"00-{format(ctx.trace_id, '032x')}-{format(ctx.span_id, '016x')}"
-        f"-{format(int(ctx.trace_flags), '02x')}"
-    )
+_ATTR_NICK = "irc.client.nick"
+_ATTR_CHANNEL = "irc.channel"
 
 
 if TYPE_CHECKING:
@@ -86,6 +62,7 @@ class Client:
         self.caps: set[str] = set()
         self.modes: set[str] = set()
         self.icon: str | None = None
+        self._session_span: _OtelSpan | None = None
 
     @property
     def prefix(self) -> str:
@@ -97,12 +74,16 @@ class Client:
         # block and `send_tagged`'s tag-stripping for non-capable clients
         # would be undone here.
         if "message-tags" in self.caps:
-            tp = _current_traceparent()
+            tp = current_traceparent()
             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
 
@@ -114,14 +95,16 @@ class Client:
         AND the client negotiated the `message-tags` capability.
         """
         if "message-tags" in self.caps:
-            tp = _current_traceparent()
+            tp = current_traceparent()
             if tp is not None:
                 # send_raw takes a pre-formatted line without an existing tag
                 # 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
 
@@ -166,35 +149,63 @@ 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
 
     async def handle(self, initial_msg: str | None = None) -> None:
-        buffer = ""
-        if initial_msg:
-            buffer = initial_msg.replace("\r\n", "\n").replace("\r", "\n")
-            buffer = await self._process_buffer(buffer)
-        while True:
-            data = await self.reader.read(4096)
-            if not data:
-                break
-            buffer += data.decode("utf-8", errors="replace")
-            # Cap buffer to prevent unbounded memory growth (512 bytes per RFC 2812)
-            if len(buffer) > 8192:
-                buffer = buffer[-4096:]
-            # Normalize all line endings to \n for simpler parsing
-            buffer = buffer.replace("\r\n", "\n").replace("\r", "\n")
-            buffer = await self._process_buffer(buffer)
+        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},
+        ) as span:
+            self._session_span = span
+            try:
+                buffer = ""
+                if initial_msg:
+                    buffer = initial_msg.replace("\r\n", "\n").replace("\r", "\n")
+                    buffer = await self._process_buffer(buffer)
+                while True:
+                    data = await self.reader.read(4096)
+                    if not data:
+                        break
+                    buffer += data.decode("utf-8", errors="replace")
+                    # Cap buffer to prevent unbounded memory growth (512 bytes per RFC 2812)
+                    if len(buffer) > 8192:
+                        buffer = buffer[-4096:]
+                    # Normalize all line endings to \n for simpler parsing
+                    buffer = buffer.replace("\r\n", "\n").replace("\r", "\n")
+                    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)
-        parent_ctx = None
+        self.server.metrics.trace_inbound.add(1, {"result": extract.status, "peer": ""})
         if extract.status == "valid":
-            parent_ctx = _context_from_traceparent(extract.traceparent)
+            parent_ctx: _OtelContext | None = context_from_traceparent(extract.traceparent)
+        else:
+            parent_ctx = _OtelContext()  # force root: detach from session span
 
+        verb = msg.command.upper()
         attrs = {
-            "irc.command": msg.command,
+            "irc.command": verb,
             "irc.prefix_nick": (msg.prefix.split("!")[0] if msg.prefix else ""),
             "culture.trace.origin": "local" if extract.status == "missing" else "remote",
         }
@@ -202,8 +213,9 @@ 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.{msg.command}",
+            f"irc.command.{verb}",
             context=parent_ctx,
             attributes=attrs,
         ):
@@ -223,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 ""
@@ -304,6 +319,8 @@ class Client:
 
         self.nick = nick
         self.server.clients[nick] = self
+        if self._session_span is not None:
+            self._session_span.set_attribute(_ATTR_NICK, nick)
         await self._try_register()
 
     async def _handle_user(self, msg: Message) -> None:
@@ -355,45 +372,49 @@ class Client:
             return
 
         channel_name = msg.params[0]
-        if not channel_name.startswith("#"):
-            return
+        with _otel_trace.get_tracer(_TRACER_NAME).start_as_current_span(
+            "irc.join",
+            attributes={_ATTR_CHANNEL: channel_name, _ATTR_NICK: self.nick or ""},
+        ):
+            if not channel_name.startswith("#"):
+                return
 
-        # Block joins to archived rooms
-        existing = self.server.channels.get(channel_name)
-        if existing and existing.archived:
-            await self.send(
-                Message(
-                    prefix=self.server.config.name,
-                    command="NOTICE",
-                    params=[self.nick, f"{channel_name} is archived and cannot be joined"],
+            # Block joins to archived rooms
+            existing = self.server.channels.get(channel_name)
+            if existing and existing.archived:
+                await self.send(
+                    Message(
+                        prefix=self.server.config.name,
+                        command="NOTICE",
+                        params=[self.nick, f"{channel_name} is archived and cannot be joined"],
+                    )
                 )
-            )
-            return
+                return
 
-        channel = self.server.get_or_create_channel(channel_name)
-        if self in channel.members:
-            return
+            channel = self.server.get_or_create_channel(channel_name)
+            if self in channel.members:
+                return
 
-        channel.add(self)
-        self.channels.add(channel)
+            channel.add(self)
+            self.channels.add(channel)
 
-        # Notify all channel members (including self)
-        join_msg = Message(prefix=self.prefix, command="JOIN", params=[channel_name])
-        for member in list(channel.members):
-            await member.send(join_msg)
+            # Notify all channel members (including self)
+            join_msg = Message(prefix=self.prefix, command="JOIN", params=[channel_name])
+            for member in list(channel.members):
+                await member.send(join_msg)
 
-        # Send topic if set
-        if channel.topic:
-            await self.send_numeric(replies.RPL_TOPIC, channel_name, channel.topic)
+            # Send topic if set
+            if channel.topic:
+                await self.send_numeric(replies.RPL_TOPIC, channel_name, channel.topic)
 
-        # Send names list
-        await self._send_names(channel)
+            # Send names list
+            await self._send_names(channel)
 
-        # Emit event AFTER delivering all join-related numerics (topic, NAMES)
-        # so that the event PRIVMSG doesn't interleave with 353/366 in client buffers.
-        await self.server.emit_event(
-            Event(type=EventType.JOIN, channel=channel_name, nick=self.nick)
-        )
+            # Emit event AFTER delivering all join-related numerics (topic, NAMES)
+            # so that the event PRIVMSG doesn't interleave with 353/366 in client buffers.
+            await self.server.emit_event(
+                Event(type=EventType.JOIN, channel=channel_name, nick=self.nick)
+            )
 
     async def _handle_part(self, msg: Message) -> None:
         if not msg.params:
@@ -401,36 +422,40 @@ class Client:
             return
 
         channel_name = msg.params[0]
-        reason = msg.params[1] if len(msg.params) > 1 else ""
+        with _otel_trace.get_tracer(_TRACER_NAME).start_as_current_span(
+            "irc.part",
+            attributes={_ATTR_CHANNEL: channel_name, _ATTR_NICK: self.nick or ""},
+        ):
+            reason = msg.params[1] if len(msg.params) > 1 else ""
 
-        channel = self.server.channels.get(channel_name)
-        if not channel or self not in channel.members:
-            await self.send_numeric(
-                replies.ERR_NOTONCHANNEL,
-                channel_name,
-                replies.MSG_NOTONCHANNEL,
-            )
-            return
+            channel = self.server.channels.get(channel_name)
+            if not channel or self not in channel.members:
+                await self.send_numeric(
+                    replies.ERR_NOTONCHANNEL,
+                    channel_name,
+                    replies.MSG_NOTONCHANNEL,
+                )
+                return
 
-        part_params = [channel_name, reason] if reason else [channel_name]
-        part_msg = Message(prefix=self.prefix, command="PART", params=part_params)
-        for member in list(channel.members):
-            await member.send(part_msg)
+            part_params = [channel_name, reason] if reason else [channel_name]
+            part_msg = Message(prefix=self.prefix, command="PART", params=part_params)
+            for member in list(channel.members):
+                await member.send(part_msg)
 
-        await self.server.emit_event(
-            Event(
-                type=EventType.PART,
-                channel=channel_name,
-                nick=self.nick,
-                data={"reason": reason},
+            await self.server.emit_event(
+                Event(
+                    type=EventType.PART,
+                    channel=channel_name,
+                    nick=self.nick,
+                    data={"reason": reason},
+                )
             )
-        )
 
-        channel.remove(self)
-        self.channels.discard(channel)
+            channel.remove(self)
+            self.channels.discard(channel)
 
-        if not channel.members and not channel.persistent:
-            del self.server.channels[channel_name]
+            if not channel.members and not channel.persistent:
+                del self.server.channels[channel_name]
 
     async def _handle_topic(self, msg: Message) -> None:
         if not msg.params:
@@ -726,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
@@ -760,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.2.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.2.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