labcode 0.1.7__tar.gz → 0.1.8__tar.gz

{labcode-0.1.7 → labcode-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labcode
-Version: 0.1.7
+Version: 0.1.8
 Summary: labcode -- a dialect wrapper over the Object-Flow Programming Language toolchain
 Author-email: Kazunari Kaizu <kwaizu@gmail.com>
 License-Expression: MIT
@@ -26,17 +26,20 @@ Requires-Dist: ofplang-run>=0.1.13
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 Requires-Dist: opentelemetry-sdk>=1.20; extra == "test"
+Requires-Dist: opentelemetry-instrumentation-grpc[instruments]>=0.41b0; extra == "test"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: ruff>=0.16; extra == "dev"
 Requires-Dist: mypy>=1.11; extra == "dev"
 Requires-Dist: opentelemetry-sdk>=1.20; extra == "dev"
+Requires-Dist: opentelemetry-instrumentation-grpc[instruments]>=0.41b0; extra == "dev"
 Provides-Extra: sila2
 Requires-Dist: sila2>=0.14; extra == "sila2"
 Provides-Extra: otel
 Requires-Dist: opentelemetry-api>=1.20; extra == "otel"
 Requires-Dist: opentelemetry-sdk>=1.20; extra == "otel"
 Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20; extra == "otel"
+Requires-Dist: opentelemetry-instrumentation-grpc>=0.41b0; extra == "otel"
 Dynamic: license-file
 
 # labcode
@@ -110,9 +113,9 @@ What `lc run` brings of its own, beyond dispatching:
   (§1.6). The client library itself is the `sila2` extra: `pip install labcode[sila2]`,
   installed into whichever interpreter runs the scripts.
 - **recording a run** — with `--trace`, what the run did is recorded as OpenTelemetry
-  traces: one trace per run, a span per operation, and a span per SiLA2 connection and
-  command measured inside the process that issued it. Off by default; the extra is
-  `pip install labcode[otel]`.
+  traces: one trace per run, a span per operation, and — measured inside the process that
+  issued them — a span per SiLA2 connection, per command, and per gRPC call underneath
+  either. Off by default; the extra is `pip install labcode[otel]`.
 
 ## Usage
 
@@ -198,14 +201,17 @@ pip install 'labcode[otel]'
 lc run <workflow> --env <env> --trace --mission-id M-2026-001
 ```
 
-One run is one trace, and the id it can be found by is printed to stderr as the run starts:
+One run is one trace, and the id it can be found by is printed to stderr as the run
+starts (`lc run: recording this run as trace …`). What it holds:
 
 ```text
 run                                  mission.id, and the failure if it stopped on one
 ├─ process Seal                      which node, process and mode; the plan's interval;
 │  │                                 which Objects it handled
 │  ├─ sila2.connect                  the address, measured in the process that connected
+│  │  └─ /…/SiLAService/GetFeatureDefinition   one per feature, × however many
 │  └─ sila2 SealerControl.Seal       the command, from its start to its real completion
+│     └─ /…/SealerControl/Seal       the round trip that started it
 └─ transport                         the route and the transporter
 ```
 
@@ -215,6 +221,16 @@ in the command spans, which are measured where the commands are issued. `ofp.obj
 lists the `_id`s an operation handled, including one it created — which is what makes
 "everything that happened to this plate" a single query.
 
+The innermost layer is the gRPC calls themselves, each under the connection or the command
+that issued it — so what a connection spends is broken down into the feature definitions it
+had to fetch, and a command's span separates its round trip from the time the instrument
+then took. It needs `grpcio`, which arrives with the `sila2` extra; without it the record is
+the same minus that layer. Two things it does not do: an observable command's
+execution-info subscription is **not** recorded (it is read on a thread of `sila2`'s own,
+where it would land in a trace of its own, and its duration is the command's anyway), and
+each recorded call **sends the trace context to the instrument** in its gRPC metadata, which
+a SiLA2 server ignores as it does any key that is not SiLA Client Metadata.
+
 Where the record goes is configured by the **standard `OTEL_*` environment variables**
 (`OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_RESOURCE_ATTRIBUTES`, `OTEL_SERVICE_NAME`, …), so
 labcode adds no settings of its own; `service.name` falls back to `labcode` if nothing sets

{labcode-0.1.7 → labcode-0.1.8}/README.md

@@ -69,9 +69,9 @@ What `lc run` brings of its own, beyond dispatching:
   (§1.6). The client library itself is the `sila2` extra: `pip install labcode[sila2]`,
   installed into whichever interpreter runs the scripts.
 - **recording a run** — with `--trace`, what the run did is recorded as OpenTelemetry
-  traces: one trace per run, a span per operation, and a span per SiLA2 connection and
-  command measured inside the process that issued it. Off by default; the extra is
-  `pip install labcode[otel]`.
+  traces: one trace per run, a span per operation, and — measured inside the process that
+  issued them — a span per SiLA2 connection, per command, and per gRPC call underneath
+  either. Off by default; the extra is `pip install labcode[otel]`.
 
 ## Usage
 
@@ -157,14 +157,17 @@ pip install 'labcode[otel]'
 lc run <workflow> --env <env> --trace --mission-id M-2026-001
 ```
 
-One run is one trace, and the id it can be found by is printed to stderr as the run starts:
+One run is one trace, and the id it can be found by is printed to stderr as the run
+starts (`lc run: recording this run as trace …`). What it holds:
 
 ```text
 run                                  mission.id, and the failure if it stopped on one
 ├─ process Seal                      which node, process and mode; the plan's interval;
 │  │                                 which Objects it handled
 │  ├─ sila2.connect                  the address, measured in the process that connected
+│  │  └─ /…/SiLAService/GetFeatureDefinition   one per feature, × however many
 │  └─ sila2 SealerControl.Seal       the command, from its start to its real completion
+│     └─ /…/SealerControl/Seal       the round trip that started it
 └─ transport                         the route and the transporter
 ```
 
@@ -174,6 +177,16 @@ in the command spans, which are measured where the commands are issued. `ofp.obj
 lists the `_id`s an operation handled, including one it created — which is what makes
 "everything that happened to this plate" a single query.
 
+The innermost layer is the gRPC calls themselves, each under the connection or the command
+that issued it — so what a connection spends is broken down into the feature definitions it
+had to fetch, and a command's span separates its round trip from the time the instrument
+then took. It needs `grpcio`, which arrives with the `sila2` extra; without it the record is
+the same minus that layer. Two things it does not do: an observable command's
+execution-info subscription is **not** recorded (it is read on a thread of `sila2`'s own,
+where it would land in a trace of its own, and its duration is the command's anyway), and
+each recorded call **sends the trace context to the instrument** in its gRPC metadata, which
+a SiLA2 server ignores as it does any key that is not SiLA Client Metadata.
+
 Where the record goes is configured by the **standard `OTEL_*` environment variables**
 (`OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_RESOURCE_ATTRIBUTES`, `OTEL_SERVICE_NAME`, …), so
 labcode adds no settings of its own; `service.name` falls back to `labcode` if nothing sets

{labcode-0.1.7 → labcode-0.1.8}/labcode/otel.py

@@ -2,9 +2,9 @@
 
 This is the half that knows OpenTelemetry. It sets up the provider, records the run and its
 operations, hands a child process what it needs to join the same trace, and -- in that child --
-resumes from it and instruments the SiLA2 client (`labcode.sila2_instrument` via
-`labcode.otel_sila2`). Replacing it means writing one more module like this one and adding two
-lines to `labcode.record`; see that module's docstring.
+resumes from it and instruments the SiLA2 client (`labcode.sila2_instrument` and the gRPC calls
+underneath it, both via `labcode.otel_sila2`). Replacing it means writing one more module like
+this one and adding two lines to `labcode.record`; see that module's docstring.
 
 **Configuration is OpenTelemetry's own.** The endpoint, headers, timeouts, resource attributes
 and sampling all come from the standard ``OTEL_*`` environment variables, so an operator
@@ -47,7 +47,7 @@ from opentelemetry.sdk.trace import ReadableSpan, TracerProvider
 from opentelemetry.sdk.trace.export import BatchSpanProcessor, SpanExporter, SpanExportResult
 from opentelemetry.trace import Span, Status, StatusCode
 
-from labcode.otel_sila2 import ATTR_ERROR_TYPE, OtelSink
+from labcode.otel_sila2 import ATTR_ERROR_TYPE, OtelSink, instrument_grpc, uninstrument_grpc
 from labcode.record import ATTR_MISSION, RUN_STOPPED, SPAN_RUN
 from labcode.sila2_instrument import (
     PROTOBUF_ENV,
@@ -281,6 +281,7 @@ class ChildSession:
 
     def finish(self) -> None:
         uninstrument_sila2()
+        uninstrument_grpc()
         context.detach(self.token)
         if self.owned:
             self.provider.shutdown()  # flushes what has not been exported yet
@@ -315,4 +316,7 @@ def resume_from_env(
         carrier["tracestate"] = tracestate
     token = context.attach(propagate.extract(carrier))
     instrument_sila2(OtelSink(tracer=resolved.get_tracer("labcode.sila2")), targets=targets)
+    # Here, rather than anywhere later: what it wraps is the factory a channel comes from, so
+    # every client the script opens has to come after it. This is the process's startup.
+    instrument_grpc()
     return ChildSession(provider=resolved, owned=owned, token=token)

labcode-0.1.8/labcode/otel_sila2.py

@@ -0,0 +1,182 @@
+"""The `Sink` that turns `labcode.sila2_instrument`'s measured units into OpenTelemetry spans.
+
+The instrumentation decides *what* is worth measuring; this decides *how it is recorded*. Swapping
+the recording backend means rewriting this file -- and leaving the instrumentation, where the
+difficult part lives (which calls to intervene in, how an observable command's real extent is
+observed), untouched.
+
+**It configures no provider**, only `trace.get_tracer`. Choosing an exporter and the resource
+attributes is the application's job (`labcode.otel` for a run; a UI that drives instruments
+directly does it for itself). That is the OpenTelemetry convention, and it has a useful
+consequence: with no provider configured the whole thing is a no-op, so a child process that is
+not recording needs no flag of its own to check.
+
+Spans are started **without becoming the current span** (`start_span`, not
+`start_as_current_span`). An observable command's span stays open until its responses are
+collected, and must not adopt the script code that runs meanwhile; wrapping the windows where an
+RPC actually runs is the instrumentation's job, through `active`.
+
+**It also records the transport underneath** (`instrument_grpc`), which is what those windows
+were for: every gRPC call a SiLA2 client makes becomes a span under the connection or the command
+that issued it, so a connection's cost breaks down into the feature definitions it fetched and a
+command's into the round trip it really was. That half is OpenTelemetry's own gRPC instrumentation
+rather than anything written here -- the only decision this module makes about it is which calls
+are worth a span (`_unary_only`).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import warnings
+from collections.abc import Mapping
+from contextlib import AbstractContextManager
+from typing import Any
+
+from opentelemetry import trace
+from opentelemetry.trace import Span, SpanKind, Status, StatusCode
+
+from labcode.sila2_instrument import KIND_CLIENT
+
+#: Measured-unit kind -> span kind. A call to an instrument is a CLIENT span; left unset it would
+#: be INTERNAL, and the record would no longer say that it left this process.
+_KINDS = {KIND_CLIENT: SpanKind.CLIENT}
+
+#: Where a failure's kind goes (the OpenTelemetry convention).
+ATTR_ERROR_TYPE = "error.type"
+
+
+class OtelSink:
+    """`labcode.sila2_instrument.Sink`, recorded as OpenTelemetry spans."""
+
+    def __init__(self, tracer: Any | None = None) -> None:
+        # Fetching the tracer eagerly is safe: the API returns one that does nothing until a
+        # provider is configured, and follows the provider once one is.
+        self._tracer = tracer if tracer is not None else trace.get_tracer("labcode.sila2")
+
+    def start(self, name: str, *, kind: str, attributes: Mapping[str, Any]) -> Span:
+        return self._tracer.start_span(
+            name, kind=_KINDS.get(kind, SpanKind.INTERNAL), attributes=dict(attributes)
+        )
+
+    def update(self, handle: Span, attributes: Mapping[str, Any]) -> None:
+        for key, value in attributes.items():
+            handle.set_attribute(key, value)
+
+    def end(
+        self, handle: Span, *, error_type: str | None = None, message: str | None = None
+    ) -> None:
+        if error_type is not None:
+            handle.set_attribute(ATTR_ERROR_TYPE, error_type)
+            handle.set_status(Status(StatusCode.ERROR, message))
+        handle.end()
+
+    def active(self, handle: Span) -> AbstractContextManager[Any]:
+        # `end_on_exit=False`: this window only lends the current context. How long the span lives
+        # is the instrumentation's to decide -- an observable command opens two windows before it
+        # ends.
+        return trace.use_span(handle, end_on_exit=False)
+
+
+# -- the transport underneath -------------------------------------------------------------
+
+
+#: Whether **this module** wrapped gRPC's channel factories, and so whether unwrapping them is
+#: its business. The same rule `labcode.otel.build_provider` follows for a provider: what another
+#: program set up is that program's to take down.
+_applied_here = False
+
+
+def _unary_only(client_info: Any) -> bool:
+    """Which gRPC calls are recorded: **unary calls yes, server streams no.**
+
+    A SiLA2 observable command opens a server stream for its execution info and `sila2` consumes
+    it on a thread of its own, which makes recording that stream wrong in two ways. The span
+    would be opened on the first iteration -- on that thread, where nothing is current -- and so
+    would land in **a trace of its own** instead of under the command it belongs to, because a
+    context is per thread. And intercepting the call replaces the stream with a generator, which
+    no longer answers `cancel()`, so `sila2`'s own `cancel_execution_info_subscription` would
+    break on it. Letting the call through leaves both alone, and gives up nothing: how long the
+    subscription lasted is exactly what the command's own span already measures.
+
+    Nothing is filtered by *name*: the feature definitions a client fetches while it is being
+    built are recorded here, under the connection, which is why they are not measured a second
+    time as commands (see `labcode.sila2_instrument`).
+    """
+    return not getattr(client_info, "is_server_stream", False)
+
+
+def instrument_grpc() -> bool:
+    """Have this process's gRPC client calls recorded, and say whether they will be.
+
+    This is the one thing here that reads the **globally configured** provider rather than being
+    handed a tracer: OpenTelemetry's gRPC instrumentation takes its provider from the channel it
+    wraps, and a `sila2` client builds its own channel. So the application must have configured
+    a provider before this is called -- as `labcode.otel.resume_from_env` does -- and with none
+    configured the RPC spans are no-ops like everything else here.
+
+    **It must run before any channel exists.** What is wrapped is `grpc.insecure_channel` and
+    `grpc.secure_channel`, so a channel built before this returns is never intercepted; a child
+    process does it at startup, ahead of the script that opens the clients.
+
+    Returns `False`, and says nothing, when there is no gRPC instrumentation installed (or no
+    `grpcio` for it to instrument): the connection and command spans do not depend on it, and an
+    interpreter that drives no instruments is right not to carry it. It warns only for the
+    surprising case -- the instrumentation is here, and still could not be applied.
+
+    Channel factories somebody else already wrapped are **left as they are** (and reported as
+    recording): reconfiguring another program's instrumentation, and later removing it, is not
+    this module's to do.
+    """
+    global _applied_here
+    try:
+        from opentelemetry.instrumentation.grpc import GrpcInstrumentorClient
+    except ImportError:
+        return False  # no gRPC instrumentation here, or no gRPC under it
+    if _channel_factories_wrapped():
+        return True
+    try:
+        # The client only. A run drives instruments; it serves nothing.
+        GrpcInstrumentorClient(filter_=_unary_only).instrument()
+    except Exception as exc:
+        _warn_not_applied(str(exc))
+        return False
+    if not _channel_factories_wrapped():
+        # `instrument()` reports a dependency it cannot satisfy by logging and returning, so
+        # what it did has to be read off the world rather than off its return value.
+        _warn_not_applied("gRPC's channel factories were left as they were")
+        return False
+    _applied_here = True
+    return True
+
+
+def uninstrument_grpc() -> None:
+    """Put gRPC's channel factories back, if this module was what wrapped them."""
+    global _applied_here
+    if not _applied_here:
+        return
+    _applied_here = False
+    with contextlib.suppress(Exception):
+        from opentelemetry.instrumentation.grpc import GrpcInstrumentorClient
+
+        GrpcInstrumentorClient().uninstrument()
+
+
+def _channel_factories_wrapped() -> bool:
+    """Whether gRPC's channel factories are intercepted -- a fact about the process, which is
+    what matters here, rather than about the instrumentor's own bookkeeping."""
+    try:
+        import grpc
+    except ImportError:
+        return False
+    return all(
+        hasattr(getattr(grpc, name, None), "__wrapped__")
+        for name in ("insecure_channel", "secure_channel")
+    )
+
+
+def _warn_not_applied(reason: str) -> None:
+    warnings.warn(
+        f"labcode: cannot instrument gRPC, so this run records no RPCs under its SiLA2 "
+        f"calls: {reason}",
+        stacklevel=3,
+    )

{labcode-0.1.7 → labcode-0.1.8}/labcode/sila2_instrument.py

@@ -6,6 +6,13 @@ themselves, and takes **one connection and one command** as the units worth meas
 Feature or Command therefore becomes measurable by existing, with no telemetry code added to any
 script.
 
+**Not everything a client does is worth a unit.** Building one makes `sila2` fetch the definition
+of every feature the server implements -- nine RPCs for one machine in the reference lab, and over
+half of everything a real run recorded. Those are not measured (`_building_a_client`), because
+they are the same RPCs a gRPC instrumentation records, and it records them *under* the connection;
+measuring them here as well would count one call twice. What they cost stays visible as most of
+`sila2.connect`, which is a unit.
+
 **It does not know where the record goes.** Turning a measured unit into a record is the `Sink`'s
 job (`labcode.otel_sila2` is the OpenTelemetry one); what lives here is only the *semantics* --
 which calls are worth measuring, when one begins, and when it has really ended. Replacing the
@@ -335,6 +342,37 @@ def _active(handle: Any) -> Iterator[None]:
                 entered.__exit__(None, None, None)
 
 
+#: Whether this thread is inside a client's construction. Per thread, because a script may open
+#: clients from several.
+_building = threading.local()
+
+
+@contextlib.contextmanager
+def _building_a_client() -> Iterator[None]:
+    """The stretch in which `sila2` is building a client, during which **commands are not
+    measured**.
+
+    What happens in there is the fetching of every feature definition the server implements --
+    nine RPCs for one machine in the reference lab, and 54 of the 101 units one real run
+    recorded before this. They are left to the gRPC instrumentation that records the same RPCs,
+    under the connection they belong to; measuring them here as well would be one call counted
+    twice, and an RPC path is a truer name for a transport than a command name is. What they
+    cost stays visible as most of `sila2.connect`.
+
+    Recognised by *when* they happen rather than by what they are called: a construction is a
+    fact, whereas a name is a guess about what `sila2` fetches in there."""
+    depth = getattr(_building, "depth", 0)
+    _building.depth = depth + 1
+    try:
+        yield
+    finally:
+        _building.depth = depth
+
+
+def _inside_a_client_build() -> bool:
+    return getattr(_building, "depth", 0) > 0
+
+
 def _remember(handle: Any) -> None:
     state = _state
     if state is None or handle is None:
@@ -438,9 +476,15 @@ def _patch_client_init(state: _State) -> None:
             attributes[ATTR_ADDRESS] = str(address)
         if port is not None:
             attributes[ATTR_PORT] = port
+        # Always measured: it is a cost every operation pays and cannot avoid (0.4-0.9 s against
+        # the reference lab, 16% of one run's wall clock), it is not recoverable from anything
+        # else the record holds, and it is what a later gRPC instrumentation hangs its per-RPC
+        # spans from.
         handle = _start(SPAN_CONNECT, attributes)
         try:
-            with _active(handle):
+            # Everything `sila2` fetches to build the client happens in here, which is how
+            # those commands are recognised (`_building_a_client`).
+            with _active(handle), _building_a_client():
                 original(self, *args, **kwargs)
         except BaseException as exc:
             _end(handle, error_type=_error_type(exc), message=str(exc))
@@ -457,6 +501,8 @@ def _patch_unobservable_call(state: _State) -> None:
 
     @functools.wraps(original)
     def __call__(self: Any, *args: Any, **kwargs: Any) -> Any:
+        if _inside_a_client_build():
+            return original(self, *args, **kwargs)  # not a unit; see `_building_a_client`
         name, attributes = _command_span(self)
         handle = _start(name, attributes)
         try:
@@ -478,6 +524,8 @@ def _patch_observable_call(state: _State) -> None:
 
     @functools.wraps(original)
     def __call__(self: Any, *args: Any, **kwargs: Any) -> Any:
+        if _inside_a_client_build():
+            return original(self, *args, **kwargs)  # not a unit; see `_building_a_client`
         name, attributes = _command_span(self)
         handle = _start(name, attributes)
         try:

{labcode-0.1.7 → labcode-0.1.8}/labcode.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labcode
-Version: 0.1.7
+Version: 0.1.8
 Summary: labcode -- a dialect wrapper over the Object-Flow Programming Language toolchain
 Author-email: Kazunari Kaizu <kwaizu@gmail.com>
 License-Expression: MIT
@@ -26,17 +26,20 @@ Requires-Dist: ofplang-run>=0.1.13
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 Requires-Dist: opentelemetry-sdk>=1.20; extra == "test"
+Requires-Dist: opentelemetry-instrumentation-grpc[instruments]>=0.41b0; extra == "test"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: ruff>=0.16; extra == "dev"
 Requires-Dist: mypy>=1.11; extra == "dev"
 Requires-Dist: opentelemetry-sdk>=1.20; extra == "dev"
+Requires-Dist: opentelemetry-instrumentation-grpc[instruments]>=0.41b0; extra == "dev"
 Provides-Extra: sila2
 Requires-Dist: sila2>=0.14; extra == "sila2"
 Provides-Extra: otel
 Requires-Dist: opentelemetry-api>=1.20; extra == "otel"
 Requires-Dist: opentelemetry-sdk>=1.20; extra == "otel"
 Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20; extra == "otel"
+Requires-Dist: opentelemetry-instrumentation-grpc>=0.41b0; extra == "otel"
 Dynamic: license-file
 
 # labcode
@@ -110,9 +113,9 @@ What `lc run` brings of its own, beyond dispatching:
   (§1.6). The client library itself is the `sila2` extra: `pip install labcode[sila2]`,
   installed into whichever interpreter runs the scripts.
 - **recording a run** — with `--trace`, what the run did is recorded as OpenTelemetry
-  traces: one trace per run, a span per operation, and a span per SiLA2 connection and
-  command measured inside the process that issued it. Off by default; the extra is
-  `pip install labcode[otel]`.
+  traces: one trace per run, a span per operation, and — measured inside the process that
+  issued them — a span per SiLA2 connection, per command, and per gRPC call underneath
+  either. Off by default; the extra is `pip install labcode[otel]`.
 
 ## Usage
 
@@ -198,14 +201,17 @@ pip install 'labcode[otel]'
 lc run <workflow> --env <env> --trace --mission-id M-2026-001
 ```
 
-One run is one trace, and the id it can be found by is printed to stderr as the run starts:
+One run is one trace, and the id it can be found by is printed to stderr as the run
+starts (`lc run: recording this run as trace …`). What it holds:
 
 ```text
 run                                  mission.id, and the failure if it stopped on one
 ├─ process Seal                      which node, process and mode; the plan's interval;
 │  │                                 which Objects it handled
 │  ├─ sila2.connect                  the address, measured in the process that connected
+│  │  └─ /…/SiLAService/GetFeatureDefinition   one per feature, × however many
 │  └─ sila2 SealerControl.Seal       the command, from its start to its real completion
+│     └─ /…/SealerControl/Seal       the round trip that started it
 └─ transport                         the route and the transporter
 ```
 
@@ -215,6 +221,16 @@ in the command spans, which are measured where the commands are issued. `ofp.obj
 lists the `_id`s an operation handled, including one it created — which is what makes
 "everything that happened to this plate" a single query.
 
+The innermost layer is the gRPC calls themselves, each under the connection or the command
+that issued it — so what a connection spends is broken down into the feature definitions it
+had to fetch, and a command's span separates its round trip from the time the instrument
+then took. It needs `grpcio`, which arrives with the `sila2` extra; without it the record is
+the same minus that layer. Two things it does not do: an observable command's
+execution-info subscription is **not** recorded (it is read on a thread of `sila2`'s own,
+where it would land in a trace of its own, and its duration is the command's anyway), and
+each recorded call **sends the trace context to the instrument** in its gRPC metadata, which
+a SiLA2 server ignores as it does any key that is not SiLA Client Metadata.
+
 Where the record goes is configured by the **standard `OTEL_*` environment variables**
 (`OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_RESOURCE_ATTRIBUTES`, `OTEL_SERVICE_NAME`, …), so
 labcode adds no settings of its own; `service.name` falls back to `labcode` if nothing sets

{labcode-0.1.7 → labcode-0.1.8}/labcode.egg-info/SOURCES.txt

@@ -63,6 +63,7 @@ tests/test_dialect.py
 tests/test_objectid.py
 tests/test_otel.py
 tests/test_otel_child.py
+tests/test_otel_grpc.py
 tests/test_otel_sila2.py
 tests/test_probe.py
 tests/test_record.py

{labcode-0.1.7 → labcode-0.1.8}/labcode.egg-info/requires.txt

@@ -7,11 +7,13 @@ pytest>=7.0
 ruff>=0.16
 mypy>=1.11
 opentelemetry-sdk>=1.20
+opentelemetry-instrumentation-grpc[instruments]>=0.41b0
 
 [otel]
 opentelemetry-api>=1.20
 opentelemetry-sdk>=1.20
 opentelemetry-exporter-otlp-proto-http>=1.20
+opentelemetry-instrumentation-grpc>=0.41b0
 
 [sila2]
 sila2>=0.14
@@ -19,3 +21,4 @@ sila2>=0.14
 [test]
 pytest>=7.0
 opentelemetry-sdk>=1.20
+opentelemetry-instrumentation-grpc[instruments]>=0.41b0

{labcode-0.1.7 → labcode-0.1.8}/labcode.egg-info/scm_file_list.json

@@ -63,6 +63,7 @@
     "tests/test_objectid.py",
     "tests/test_otel.py",
     "tests/test_otel_child.py",
+    "tests/test_otel_grpc.py",
     "tests/test_otel_sila2.py",
     "tests/test_probe.py",
     "tests/test_record.py",

{labcode-0.1.7 → labcode-0.1.8}/labcode.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.1.7",
+  "tag": "0.1.8",
   "distance": 0,
-  "node": "g5ac30ea05ab94fb91cc31c75db1c96a11d51eb19",
+  "node": "g6afb1daec9a83355371efb2f4a4151b275e4fd73",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-21"

{labcode-0.1.7 → labcode-0.1.8}/pyproject.toml

@@ -50,8 +50,22 @@ Repository = "https://github.com/ofplang/labcode"
 # skipped test asserts nothing -- so CI has to be able to run them. And mypy is configured
 # with `ignore_missing_imports`, which quietly turns an absent SDK's types into `Any`: that
 # is how two real type errors in `labcode/otel.py` survived until the SDK was installed.
-test = ["pytest>=7.0", "opentelemetry-sdk>=1.20"]
-dev = ["pytest>=7.0", "ruff>=0.16", "mypy>=1.11", "opentelemetry-sdk>=1.20"]
+# The gRPC instrumentation is here for the first of those reasons, and it is asked for
+# *with* its own `instruments` extra -- meaning `grpcio` -- because what the tests check is
+# that a server-streaming call is passed through untouched, and there is no interceptor to
+# hand a call to without the library it intercepts.
+test = [
+    "pytest>=7.0",
+    "opentelemetry-sdk>=1.20",
+    "opentelemetry-instrumentation-grpc[instruments]>=0.41b0",
+]
+dev = [
+    "pytest>=7.0",
+    "ruff>=0.16",
+    "mypy>=1.11",
+    "opentelemetry-sdk>=1.20",
+    "opentelemetry-instrumentation-grpc[instruments]>=0.41b0",
+]
 # Only the SiLA2 integration example needs a SiLA2 client, and it needs it in whatever
 # interpreter runs the scripts: labcode launches each one with `sys.executable`. It is an
 # extra rather than a dependency because labcode itself never speaks SiLA2 -- an environment
@@ -65,10 +79,17 @@ sila2 = ["sila2>=0.14"]
 # The exporter is constructed with no arguments at all, so it asks for nothing newer; it is
 # the HTTP one deliberately, so that nothing here constrains the `grpcio` that `sila2`
 # brings into the same process.
+# The gRPC instrumentation is what puts each RPC under the connection or the command that
+# issued it -- the feature definitions a connection fetches, and a command's real round
+# trip. It brings no `grpcio` of its own (its floor on one is an extra), which is right
+# here: the `grpcio` in this process is whichever one `sila2` brought. `0.41b0` is the
+# oldest release with the `filter_` this uses, and it accepts `opentelemetry-api ~= 1.12`,
+# so it does not pull the floors above upwards.
 otel = [
     "opentelemetry-api>=1.20",
     "opentelemetry-sdk>=1.20",
     "opentelemetry-exporter-otlp-proto-http>=1.20",
+    "opentelemetry-instrumentation-grpc>=0.41b0",
 ]
 
 [project.scripts]

{labcode-0.1.7 → labcode-0.1.8}/tests/test_otel_child.py

@@ -167,3 +167,43 @@ def test_a_recording_child_gets_the_protobuf_implementation_sila2_needs(tmp_path
 
     names = [span["name"] for span in _spans(tmp_path)]
     assert "protobuf python" in names, f"the child resolved something else: {names}"
+
+
+def test_a_recording_child_has_its_grpc_calls_instrumented(tmp_path, monkeypatch):
+    """The RPCs underneath a SiLA2 call are recorded in the child, and the wrapping has to be in
+    place before the script opens a client -- so what this checks is that the *startup* did it,
+    not that some later call did. The child reports what it found, as a span name."""
+    pytest.importorskip("ofplang.schedule", reason="ofplang-schedule not installed")
+    pytest.importorskip("grpc", reason="grpcio is not installed")
+    pytest.importorskip(
+        "opentelemetry.instrumentation.grpc", reason="the gRPC instrumentation is not installed"
+    )
+    from labcode.runner import LabcodeRunner
+
+    environment = tmp_path / "env.yaml"
+    environment.write_text(
+        TENV.read_text(encoding="utf-8").replace(
+            "moved = (view, from_spot, to_spot, transporter)",
+            "import grpc; "
+            "from opentelemetry import trace; "
+            "state = 'wrapped' if hasattr(grpc.insecure_channel, '__wrapped__') else 'plain'; "
+            "trace.get_tracer('child').start_span('grpc ' + state).end()",
+        ),
+        encoding="utf-8",
+    )
+    monkeypatch.setenv("LC_TRACE_FILE", str(tmp_path / "record.jsonl"))
+    monkeypatch.setenv("OTEL_TRACES_EXPORTER", "none")
+
+    clock = FakeClock()
+    runner = LabcodeRunner(
+        TWF, str(environment), seconds_per_tick=0.001, monotonic=clock.monotonic,
+        sleep=clock.sleep, random_seed=0, running_task_margin=1, trace=True,
+    )
+    try:
+        runner.run()
+    finally:
+        runner.sim.close()
+    assert not runner.failed
+
+    names = [span["name"] for span in _spans(tmp_path)]
+    assert "grpc wrapped" in names, f"the child's gRPC calls are not recorded: {names}"

labcode-0.1.8/tests/test_otel_grpc.py

@@ -0,0 +1,153 @@
+"""Recording the gRPC calls underneath a SiLA2 call (`labcode.otel_sila2`).
+
+The spans themselves are OpenTelemetry's own gRPC instrumentation, and are not this project's to
+test. What *is* this project's is the one decision it makes about them -- which calls are worth a
+span -- and the two mechanical facts that decision rests on: that a unary call is recorded under
+whatever is current, and that a **server-streaming** call comes back exactly as it went in.
+
+That second one is the point. A SiLA2 observable command subscribes to its execution info over a
+server stream that `sila2` reads on a thread of its own, so a span for it would open where nothing
+is current and land in a trace of its own -- and the interception would hand `sila2` a generator
+in place of a stream it expects to be able to cancel. Both are avoided by not intercepting it, and
+this asserts that the object handed back is the very one the call produced.
+
+Skipped unless the gRPC instrumentation is installed, with the `grpcio` it intercepts.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+pytest.importorskip("opentelemetry.sdk", reason="the otel extra is not installed")
+pytest.importorskip(
+    "opentelemetry.instrumentation.grpc", reason="the gRPC instrumentation is not installed"
+)
+
+import grpc  # noqa: E402
+from opentelemetry.instrumentation.grpc import client_interceptor  # noqa: E402
+from opentelemetry.sdk.trace import TracerProvider  # noqa: E402
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor  # noqa: E402
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import (  # noqa: E402
+    InMemorySpanExporter,
+)
+from opentelemetry.trace import SpanKind  # noqa: E402
+
+from labcode.otel_sila2 import (  # noqa: E402
+    _unary_only,
+    instrument_grpc,
+    uninstrument_grpc,
+)
+
+#: A real SiLA2 method path: the feature definitions a client fetches while it is being built.
+#: They are deliberately *not* filtered out -- recorded here, under the connection, they are the
+#: reason `labcode.sila2_instrument` does not measure them a second time as commands.
+FETCH = "/sila2.org.silastandard.core.silaservice.v1.SiLAService/GetFeatureDefinition"
+
+#: What an observable command's execution-info subscription looks like to a filter.
+INFO_STREAM = "/sila2.org.silastandard.examples.sealer.v1.SealerControl/Seal_Info"
+
+
+@pytest.fixture
+def recorded():
+    """``(interceptor, exporter)`` recording into memory, filtered as labcode filters."""
+    exporter = InMemorySpanExporter()
+    provider = TracerProvider()
+    provider.add_span_processor(SimpleSpanProcessor(exporter))
+    interceptor = client_interceptor(tracer_provider=provider, filter_=_unary_only)
+    return interceptor, exporter
+
+
+def _unary_call(full_method: str = FETCH) -> SimpleNamespace:
+    return SimpleNamespace(full_method=full_method, timeout=None)
+
+
+def _stream_call(full_method: str = INFO_STREAM, **kwargs) -> SimpleNamespace:
+    return SimpleNamespace(
+        full_method=full_method,
+        is_client_stream=kwargs.get("is_client_stream", False),
+        is_server_stream=kwargs.get("is_server_stream", True),
+        timeout=None,
+    )
+
+
+def test_a_unary_call_is_recorded_as_a_span_named_by_its_method(recorded):
+    interceptor, exporter = recorded
+
+    result = interceptor.intercept_unary("request", (), _unary_call(), lambda r, m: "response")
+
+    assert result == "response"
+    (span,) = exporter.get_finished_spans()
+    # The name is the method path, which is how a fetch of a feature definition can be told
+    # from the command that follows it without either one being named twice.
+    assert span.name == FETCH
+    assert span.kind is SpanKind.CLIENT
+    assert span.attributes["rpc.system"] == "grpc"
+    assert span.attributes["rpc.method"] == "GetFeatureDefinition"
+    assert span.attributes["rpc.service"] == FETCH.lstrip("/").split("/")[0]
+
+
+def test_a_recorded_call_carries_the_trace_context_to_the_instrument(recorded):
+    """A recorded RPC sends the current trace context in its gRPC metadata -- a fact worth
+    asserting because it is the one thing recording changes on the wire. A SiLA2 server ignores
+    metadata that is not a SiLA Client Metadata key."""
+    interceptor, _exporter = recorded
+    seen: dict[str, str] = {}
+
+    def invoker(request, metadata):
+        seen.update(dict(metadata))
+        return "response"
+
+    interceptor.intercept_unary("request", (), _unary_call(), invoker)
+
+    assert "traceparent" in seen, f"nothing was propagated: {seen}"
+
+
+def test_a_server_stream_is_handed_back_exactly_as_it_came(recorded):
+    interceptor, exporter = recorded
+    stream = object()  # stands in for the rendezvous `sila2` keeps, and cancels
+
+    result = interceptor.intercept_stream("request", (), _stream_call(), lambda r, m: stream)
+
+    assert result is stream, "the stream was wrapped, so it no longer answers cancel()"
+    assert exporter.get_finished_spans() == ()
+
+
+def test_only_a_server_stream_is_left_out():
+    """The filter reads the one fact that distinguishes the subscription: a unary call has no
+    such attribute at all, which is why the question is asked with a default."""
+    assert _unary_only(_unary_call()) is True
+    assert _unary_only(_stream_call(is_server_stream=False, is_client_stream=True)) is True
+    assert _unary_only(_stream_call()) is False
+
+
+def test_instrumenting_wraps_the_channel_factories_and_undoes_it():
+    plain = (grpc.insecure_channel, grpc.secure_channel)
+    try:
+        assert instrument_grpc() is True
+        # A channel can only be intercepted if the factory it comes from is, which is why this
+        # has to happen before any client exists.
+        assert grpc.insecure_channel is not plain[0]
+        assert hasattr(grpc.insecure_channel, "__wrapped__")
+        assert hasattr(grpc.secure_channel, "__wrapped__")
+    finally:
+        uninstrument_grpc()
+    assert (grpc.insecure_channel, grpc.secure_channel) == plain
+
+
+def test_factories_somebody_else_wrapped_are_left_alone(monkeypatch):
+    """Reporting that RPCs are recorded, and not touching them: another program's
+    instrumentation is its own to configure and its own to remove."""
+
+    class AlreadyWrapped:
+        __wrapped__ = None
+
+    theirs = AlreadyWrapped()
+    monkeypatch.setattr(grpc, "insecure_channel", theirs)
+    monkeypatch.setattr(grpc, "secure_channel", theirs)
+
+    assert instrument_grpc() is True
+    uninstrument_grpc()
+    assert grpc.insecure_channel is theirs
+    assert grpc.secure_channel is theirs

{labcode-0.1.7 → labcode-0.1.8}/tests/test_sila2_instrument.py

@@ -106,15 +106,22 @@ class NotFinished(Exception):
 
 
 class FakeClient:
-    """Stands in for `SilaClient`: constructing one *is* the connection."""
+    """Stands in for `SilaClient`: constructing one *is* the connection.
 
-    def __init__(self, address, port, *, insecure=False, log=None, fail=None) -> None:
+    `during_init` stands in for what `sila2` does while it builds one -- fetching the
+    definition of every feature the server implements, as commands."""
+
+    def __init__(
+        self, address, port, *, insecure=False, log=None, fail=None, during_init=None
+    ) -> None:
         if log is not None:
             log.append(("connecting", address))
         if fail is not None:
             raise fail
         self.address = address
         self.port = port
+        if during_init is not None:
+            during_init(self)
 
 
 class FakeCommandDef:
@@ -490,3 +497,46 @@ def test_the_real_sila2_still_has_the_intervention_points():
     command = SiLAServiceFeature["GetFeatureDefinition"]
     assert command._identifier == "GetFeatureDefinition"
     assert str(command.fully_qualified_identifier).endswith("/Command/GetFeatureDefinition")
+
+
+# -- what building a client is not measured for -----------------------------------------
+
+
+def _client_that_fetches(sink: RecordingSink, results: list) -> FakeClient:
+    """A client whose construction issues a command, as `sila2` does when it fetches the
+    feature definitions of the server it has just reached."""
+
+    def during_init(client):
+        feature = FakeFeature("SiLAService", client)
+        command = FakeUnobservable(
+            feature, FakeCommandDef("GetFeatureDefinition"), log=sink.log, result="<feature/>"
+        )
+        results.append(command())
+
+    return FakeClient("127.0.0.1", 50057, insecure=True, log=sink.log, during_init=during_init)
+
+
+def test_what_a_client_fetches_to_build_itself_is_not_a_unit(sink):
+    """Half of a real run's units were these, and a gRPC instrumentation would record the same
+    RPCs under the connection -- so they are left to it. The connection still is a unit, and
+    what they cost is most of it."""
+    results: list = []
+
+    _client_that_fetches(sink, results)
+
+    assert results == ["<feature/>"], "the fetch itself still happens"
+    assert [handle.name for handle in sink.handles] == [SPAN_CONNECT]
+
+
+
+def test_a_command_after_the_client_is_built_is_still_a_unit(sink):
+    """The suppression is a stretch of time, not a name: what the operation itself asks the
+    instrument to do is measured as it always was."""
+    results: list = []
+    client = _client_that_fetches(sink, results)
+    feature = FakeFeature("SealerControl", client)
+    command = FakeUnobservable(feature, FakeCommandDef("Seal", SEAL_FQI), log=sink.log, result="ok")
+
+    assert command() == "ok"
+
+    assert [handle.name for handle in sink.handles] == [SPAN_CONNECT, SEAL]

labcode-0.1.7/labcode/otel_sila2.py

@@ -1,68 +0,0 @@
-"""The `Sink` that turns `labcode.sila2_instrument`'s measured units into OpenTelemetry spans.
-
-The instrumentation decides *what* is worth measuring; this decides *how it is recorded*. Swapping
-the recording backend means rewriting this file -- and leaving the instrumentation, where the
-difficult part lives (which calls to intervene in, how an observable command's real extent is
-observed), untouched.
-
-**It configures no provider**, only `trace.get_tracer`. Choosing an exporter and the resource
-attributes is the application's job (`labcode.otel` for a run; a UI that drives instruments
-directly does it for itself). That is the OpenTelemetry convention, and it has a useful
-consequence: with no provider configured the whole thing is a no-op, so a child process that is
-not recording needs no flag of its own to check.
-
-Spans are started **without becoming the current span** (`start_span`, not
-`start_as_current_span`). An observable command's span stays open until its responses are
-collected, and must not adopt the script code that runs meanwhile; wrapping the windows where an
-RPC actually runs is the instrumentation's job, through `active`.
-"""
-
-from __future__ import annotations
-
-from collections.abc import Mapping
-from contextlib import AbstractContextManager
-from typing import Any
-
-from opentelemetry import trace
-from opentelemetry.trace import Span, SpanKind, Status, StatusCode
-
-from labcode.sila2_instrument import KIND_CLIENT
-
-#: Measured-unit kind -> span kind. A call to an instrument is a CLIENT span; left unset it would
-#: be INTERNAL, and the record would no longer say that it left this process.
-_KINDS = {KIND_CLIENT: SpanKind.CLIENT}
-
-#: Where a failure's kind goes (the OpenTelemetry convention).
-ATTR_ERROR_TYPE = "error.type"
-
-
-class OtelSink:
-    """`labcode.sila2_instrument.Sink`, recorded as OpenTelemetry spans."""
-
-    def __init__(self, tracer: Any | None = None) -> None:
-        # Fetching the tracer eagerly is safe: the API returns one that does nothing until a
-        # provider is configured, and follows the provider once one is.
-        self._tracer = tracer if tracer is not None else trace.get_tracer("labcode.sila2")
-
-    def start(self, name: str, *, kind: str, attributes: Mapping[str, Any]) -> Span:
-        return self._tracer.start_span(
-            name, kind=_KINDS.get(kind, SpanKind.INTERNAL), attributes=dict(attributes)
-        )
-
-    def update(self, handle: Span, attributes: Mapping[str, Any]) -> None:
-        for key, value in attributes.items():
-            handle.set_attribute(key, value)
-
-    def end(
-        self, handle: Span, *, error_type: str | None = None, message: str | None = None
-    ) -> None:
-        if error_type is not None:
-            handle.set_attribute(ATTR_ERROR_TYPE, error_type)
-            handle.set_status(Status(StatusCode.ERROR, message))
-        handle.end()
-
-    def active(self, handle: Span) -> AbstractContextManager[Any]:
-        # `end_on_exit=False`: this window only lends the current context. How long the span lives
-        # is the instrumentation's to decide -- an observable command opens two windows before it
-        # ends.
-        return trace.use_span(handle, end_on_exit=False)