respan-instrumentation-pytest 0.1.0__tar.gz

respan_instrumentation_pytest-0.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: respan-instrumentation-pytest
+Version: 0.1.0
+Summary: Respan tracing plugin for Pytest sessions and tests
+License: Apache 2.0
+Author: Respan
+Author-email: team@respan.ai
+Requires-Python: >=3.11,<3.14
+Classifier: Framework :: Pytest
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: opentelemetry-semantic-conventions-ai (>=0.4.1)
+Requires-Dist: pytest (>=7.4.0,<10.0.0)
+Requires-Dist: respan-sdk (>=2.6.1)
+Requires-Dist: respan-tracing (>=2.17.0,<3.0.0)
+Description-Content-Type: text/markdown
+
+# respan-instrumentation-pytest
+
+An installable Pytest plugin that emits one canonical Respan workflow span for each test session and one task span for every test protocol. The test span remains current across setup, synchronous or asynchronous execution, and teardown, so application spans created by a test are nested beneath the correct test.
+
+The plugin records pass, skip, xfail, setup failure, assertion failure, teardown failure, phase duration, parametrization, markers, and fixture names. Failures include OpenTelemetry error status plus backend-visible `status_code` and `error.message` fields.
+
+## Install and enable
+
+```bash
+pip install respan-ai respan-instrumentation-pytest
+pytest --respan-tracing
+```
+
+Pytest discovers the package through its `pytest11` entry point. It remains opt-in after installation so a globally installed plugin does not unexpectedly export every test run. Enable it in CI with:
+
+```bash
+RESPAN_PYTEST_ENABLED=true pytest
+```
+
+The usual `RESPAN_API_KEY` and optional `RESPAN_BASE_URL` variables configure export. Configuration can also live in `pytest.ini`:
+
+```ini
+[pytest]
+respan_tracing = true
+respan_capture_content = true
+respan_workflow_name = checkout_integration_tests
+```
+
+Equivalent environment variables are `RESPAN_PYTEST_ENABLED`, `RESPAN_PYTEST_CAPTURE_CONTENT`, and `RESPAN_PYTEST_WORKFLOW_NAME`.
+
+## Content capture
+
+By default, test parameters, fixture names, markers, and failure text are captured. Disable sensitive values with:
+
+```bash
+pytest --respan-tracing --no-respan-capture-content
+```
+
+With capture disabled, node IDs, outcomes, phase durations, and exception types remain visible while parameter values and failure messages are omitted. Fixture return values are never recorded. Each xdist worker creates its own session span with worker metadata. The lifecycle is idempotent.
+

respan_instrumentation_pytest-0.1.0/README.md

@@ -0,0 +1,39 @@
+# respan-instrumentation-pytest
+
+An installable Pytest plugin that emits one canonical Respan workflow span for each test session and one task span for every test protocol. The test span remains current across setup, synchronous or asynchronous execution, and teardown, so application spans created by a test are nested beneath the correct test.
+
+The plugin records pass, skip, xfail, setup failure, assertion failure, teardown failure, phase duration, parametrization, markers, and fixture names. Failures include OpenTelemetry error status plus backend-visible `status_code` and `error.message` fields.
+
+## Install and enable
+
+```bash
+pip install respan-ai respan-instrumentation-pytest
+pytest --respan-tracing
+```
+
+Pytest discovers the package through its `pytest11` entry point. It remains opt-in after installation so a globally installed plugin does not unexpectedly export every test run. Enable it in CI with:
+
+```bash
+RESPAN_PYTEST_ENABLED=true pytest
+```
+
+The usual `RESPAN_API_KEY` and optional `RESPAN_BASE_URL` variables configure export. Configuration can also live in `pytest.ini`:
+
+```ini
+[pytest]
+respan_tracing = true
+respan_capture_content = true
+respan_workflow_name = checkout_integration_tests
+```
+
+Equivalent environment variables are `RESPAN_PYTEST_ENABLED`, `RESPAN_PYTEST_CAPTURE_CONTENT`, and `RESPAN_PYTEST_WORKFLOW_NAME`.
+
+## Content capture
+
+By default, test parameters, fixture names, markers, and failure text are captured. Disable sensitive values with:
+
+```bash
+pytest --respan-tracing --no-respan-capture-content
+```
+
+With capture disabled, node IDs, outcomes, phase durations, and exception types remain visible while parameter values and failure messages are omitted. Fixture return values are never recorded. Each xdist worker creates its own session span with worker metadata. The lifecycle is idempotent.

respan_instrumentation_pytest-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[tool.poetry]
+name = "respan-instrumentation-pytest"
+version = "0.1.0"
+description = "Respan tracing plugin for Pytest sessions and tests"
+authors = ["Respan <team@respan.ai>"]
+license = "Apache 2.0"
+readme = "README.md"
+classifiers = ["Framework :: Pytest"]
+packages = [
+    { include = "respan_instrumentation_pytest", from = "./src" },
+]
+
+[tool.poetry.dependencies]
+python = ">=3.11,<3.14"
+respan-tracing = "^2.17.0"
+respan-sdk = ">=2.6.1"
+pytest = ">=7.4.0,<10.0.0"
+opentelemetry-semantic-conventions-ai = ">=0.4.1"
+
+[tool.poetry.plugins."respan.instrumentations"]
+pytest = "respan_instrumentation_pytest:PytestInstrumentor"
+
+[tool.poetry.plugins.pytest11]
+respan = "respan_instrumentation_pytest.plugin"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

respan_instrumentation_pytest-0.1.0/src/respan_instrumentation_pytest/__init__.py

@@ -0,0 +1,5 @@
+from respan_instrumentation_pytest._runtime import (
+    PytestRuntimePlugin as PytestInstrumentor,
+)
+
+__all__ = ["PytestInstrumentor"]

respan_instrumentation_pytest-0.1.0/src/respan_instrumentation_pytest/_constants.py

@@ -0,0 +1,18 @@
+"""Pytest instrumentation-local constants."""
+
+from respan_sdk.constants.llm_logging import LOG_TYPE_TASK, LOG_TYPE_WORKFLOW
+
+
+PYTEST_INSTRUMENTATION_NAME = "pytest"
+PYTEST_RUNTIME_PLUGIN_NAME = "respan-pytest-runtime"
+
+ENV_ENABLED = "RESPAN_PYTEST_ENABLED"
+ENV_CAPTURE_CONTENT = "RESPAN_PYTEST_CAPTURE_CONTENT"
+ENV_WORKFLOW_NAME = "RESPAN_PYTEST_WORKFLOW_NAME"
+ENV_EXAMPLE_RUN_ID = "RESPAN_EXAMPLE_RUN_ID"
+
+TASK_LOG_TYPE = LOG_TYPE_TASK
+WORKFLOW_LOG_TYPE = LOG_TYPE_WORKFLOW
+MAX_ATTRIBUTE_CHARS = 16_000
+MAX_COLLECTION_ITEMS = 50
+MAX_SERIALIZATION_DEPTH = 8

respan_instrumentation_pytest-0.1.0/src/respan_instrumentation_pytest/_instrumentation.py

@@ -0,0 +1,289 @@
+"""Pytest hook implementation that emits canonical Respan spans."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from collections import Counter
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+from opentelemetry import trace
+from opentelemetry.semconv_ai import SpanAttributes
+from opentelemetry.trace import SpanKind
+from respan_instrumentation_pytest._constants import (
+    ENV_EXAMPLE_RUN_ID,
+    MAX_ATTRIBUTE_CHARS,
+    MAX_COLLECTION_ITEMS,
+    MAX_SERIALIZATION_DEPTH,
+    PYTEST_INSTRUMENTATION_NAME,
+    WORKFLOW_LOG_TYPE,
+)
+from respan_sdk.constants.span_attributes import (
+    RESPAN_LOG_TYPE,
+    RESPAN_METADATA,
+    RESPAN_SPAN_CUSTOM_ID,
+    RESPAN_TRACE_GROUP_ID,
+)
+from respan_tracing import RespanTelemetry
+from respan_tracing.core.tracer import RespanTracer
+
+logger = logging.getLogger(__name__)
+
+
+def _to_jsonable(value: Any, *, depth: int = 0) -> Any:
+    if depth > MAX_SERIALIZATION_DEPTH:
+        return repr(value)
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, bytes):
+        return {"type": "bytes", "length": len(value)}
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, Mapping):
+        items = list(value.items())
+        payload = {
+            str(key): _to_jsonable(item, depth=depth + 1)
+            for key, item in items[:MAX_COLLECTION_ITEMS]
+        }
+        if len(items) > MAX_COLLECTION_ITEMS:
+            payload["_respan_truncated_items"] = len(items) - MAX_COLLECTION_ITEMS
+        return payload
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+        items = list(value)
+        payload = [
+            _to_jsonable(item, depth=depth + 1) for item in items[:MAX_COLLECTION_ITEMS]
+        ]
+        if len(items) > MAX_COLLECTION_ITEMS:
+            payload.append(
+                {"_respan_truncated_items": len(items) - MAX_COLLECTION_ITEMS}
+            )
+        return payload
+    return repr(value)
+
+
+def _json_dumps(value: Any, *, max_chars: int = MAX_ATTRIBUTE_CHARS) -> str:
+    serialized = json.dumps(
+        _to_jsonable(value),
+        default=str,
+        ensure_ascii=False,
+        sort_keys=True,
+    )
+    if len(serialized) <= max_chars:
+        return serialized
+    return json.dumps(
+        {
+            "truncated": True,
+            "original_characters": len(serialized),
+            "preview": serialized[:max_chars],
+        },
+        ensure_ascii=False,
+        sort_keys=True,
+    )
+
+
+def _safe_name(value: str) -> str:
+    return "_".join(value.strip().split())[:160] or "pytest_session"
+
+
+@dataclass
+class _TestState:
+    span: Any
+    context_manager: Any
+    reports: dict[str, Any] = field(default_factory=dict)
+    durations: dict[str, float] = field(default_factory=dict)
+    error: BaseException | None = None
+    error_when: str | None = None
+
+
+class PytestInstrumentor:
+    """Actual Pytest plugin and Respan instrumentation lifecycle entrypoint."""
+
+    name = PYTEST_INSTRUMENTATION_NAME
+
+    def __init__(
+        self,
+        *,
+        capture_content: bool = True,
+        workflow_name: str | None = None,
+        tracer: Any = None,
+        max_attribute_chars: int = MAX_ATTRIBUTE_CHARS,
+    ) -> None:
+        self._capture_content = capture_content
+        self._workflow_name = workflow_name
+        self._provided_tracer = tracer
+        self._tracer: Any = None
+        self._telemetry: RespanTelemetry | None = None
+        self._max_attribute_chars = max(512, int(max_attribute_chars))
+        self._is_instrumented = False
+        self._session_span: Any = None
+        self._session_context_manager: Any = None
+        self._session: Any = None
+        self._test_states: dict[str, _TestState] = {}
+        self._outcome_counts: Counter[str] = Counter()
+        self._run_id = os.getenv(ENV_EXAMPLE_RUN_ID) or uuid4().hex[:12]
+
+    def _resolve_tracer(self) -> Any:
+        if self._provided_tracer is not None:
+            return self._provided_tracer
+        if getattr(RespanTracer, "_instance", None) is None:
+            self._telemetry = RespanTelemetry(
+                app_name=self._workflow_name or "pytest",
+                api_key=os.getenv("RESPAN_API_KEY"),
+                base_url=os.getenv("RESPAN_BASE_URL"),
+                is_auto_instrument=False,
+                is_batching_enabled=False,
+            )
+        return trace.get_tracer(__name__)
+
+    def activate(self) -> None:
+        """Prepare tracing. Pytest hook registration is handled by `plugin.py`."""
+        if self._is_instrumented:
+            return
+        self._tracer = self._resolve_tracer()
+        self._is_instrumented = True
+        logger.info("Pytest instrumentation activated")
+
+    def deactivate(self) -> None:
+        """Close any live spans and flush telemetry without altering test results."""
+        for nodeid in tuple(self._test_states):
+            state = self._test_states.pop(nodeid)
+            try:
+                self._finish_test_span(nodeid, state)
+            finally:
+                state.context_manager.__exit__(None, None, None)
+        if self._session_context_manager is not None:
+            try:
+                self._finish_session_span(exitstatus=None)
+            finally:
+                self._session_context_manager.__exit__(None, None, None)
+        self._session_context_manager = None
+        self._session_span = None
+        self._session = None
+        if self._telemetry is not None:
+            try:
+                self._telemetry.flush()
+            except Exception:
+                logger.debug("Failed to flush Pytest telemetry", exc_info=True)
+        self._is_instrumented = False
+        logger.info("Pytest instrumentation deactivated")
+
+    def _resolved_workflow_name(self, config: Any) -> str:
+        if self._workflow_name:
+            return _safe_name(self._workflow_name)
+        rootpath = getattr(config, "rootpath", Path.cwd())
+        root_name = Path(rootpath).name or "tests"
+        return _safe_name(f"pytest_{root_name}_workflow")
+
+    def _metadata(self, *, worker_id: str | None = None) -> str:
+        metadata = {
+            "integration": "pytest",
+            "workflow_name": self._workflow_name,
+            "example_run_id": self._run_id,
+        }
+        if worker_id:
+            metadata["worker_id"] = worker_id
+        return _json_dumps(metadata, max_chars=self._max_attribute_chars)
+
+    def _set_common_attributes(
+        self,
+        span: Any,
+        *,
+        log_type: str,
+        entity_name: str,
+        entity_path: str,
+        input_payload: dict[str, Any],
+        worker_id: str | None = None,
+    ) -> None:
+        span.set_attribute(RESPAN_LOG_TYPE, log_type)
+        span.set_attribute(SpanAttributes.TRACELOOP_ENTITY_NAME, entity_name)
+        span.set_attribute(SpanAttributes.TRACELOOP_ENTITY_PATH, entity_path)
+        span.set_attribute(
+            SpanAttributes.TRACELOOP_ENTITY_INPUT,
+            _json_dumps(input_payload, max_chars=self._max_attribute_chars),
+        )
+        if self._workflow_name:
+            span.set_attribute(RESPAN_TRACE_GROUP_ID, self._workflow_name)
+        span.set_attribute(RESPAN_METADATA, self._metadata(worker_id=worker_id))
+
+    def pytest_sessionstart(self, session: Any) -> None:
+        if not self._is_instrumented or self._session_span is not None:
+            return
+        try:
+            self._session = session
+            self._workflow_name = self._resolved_workflow_name(session.config)
+            worker_id = os.getenv("PYTEST_XDIST_WORKER")
+            self._session_context_manager = self._tracer.start_as_current_span(
+                "pytest.session", kind=SpanKind.INTERNAL
+            )
+            self._session_span = self._session_context_manager.__enter__()
+            self._set_common_attributes(
+                self._session_span,
+                log_type=WORKFLOW_LOG_TYPE,
+                entity_name=self._workflow_name,
+                entity_path="",
+                input_payload={
+                    "rootpath": str(getattr(session.config, "rootpath", "")),
+                    "arguments": (
+                        list(getattr(session.config, "args", ()) or ())
+                        if self._capture_content
+                        else []
+                    ),
+                    "content_captured": self._capture_content,
+                },
+                worker_id=worker_id,
+            )
+            self._session_span.set_attribute(
+                RESPAN_SPAN_CUSTOM_ID,
+                f"{self._workflow_name}-{self._run_id}"
+                + (f"-{worker_id}" if worker_id else ""),
+            )
+        except Exception:
+            logger.exception("Failed to start Pytest session span")
+            self._session_context_manager = None
+            self._session_span = None
+
+    def pytest_collection_finish(self, session: Any) -> None:
+        if self._session_span is None:
+            return
+        items = list(getattr(session, "items", ()) or ())
+        payload: dict[str, Any] = {
+            "rootpath": str(getattr(session.config, "rootpath", "")),
+            "collected": len(items),
+            "content_captured": self._capture_content,
+        }
+        if self._capture_content:
+            payload["tests"] = [getattr(item, "nodeid", str(item)) for item in items]
+        self._session_span.set_attribute(
+            SpanAttributes.TRACELOOP_ENTITY_INPUT,
+            _json_dumps(payload, max_chars=self._max_attribute_chars),
+        )
+
+    def _test_nodeid(self, item: Any) -> str:
+        nodeid = str(item.nodeid)
+        return nodeid if self._capture_content else nodeid.split("[", 1)[0]
+
+    def _test_input(self, item: Any) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "nodeid": self._test_nodeid(item),
+            "content_captured": self._capture_content,
+        }
+        if not self._capture_content:
+            return payload
+        callspec = getattr(item, "callspec", None)
+        params = getattr(callspec, "params", None)
+        if params:
+            payload["parameters"] = params
+        fixture_names = list(getattr(item, "fixturenames", ()) or ())
+        if fixture_names:
+            payload["fixtures"] = fixture_names
+        iter_markers = getattr(item, "iter_markers", None)
+        if callable(iter_markers):
+            markers = sorted({marker.name for marker in iter_markers()})
+            if markers:
+                payload["markers"] = markers
+        return payload

respan_instrumentation_pytest-0.1.0/src/respan_instrumentation_pytest/_runtime.py

@@ -0,0 +1,185 @@
+"""Runtime Pytest hooks built on the public instrumentation lifecycle."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+import pytest
+from opentelemetry.semconv_ai import SpanAttributes
+from opentelemetry.trace import SpanKind, Status, StatusCode
+
+from respan_instrumentation_pytest._constants import TASK_LOG_TYPE
+from respan_instrumentation_pytest._instrumentation import (
+    PytestInstrumentor,
+    _TestState,
+    _json_dumps,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class PytestRuntimePlugin(PytestInstrumentor):
+    """Pytest hook implementation registered by the `pytest11` entry point."""
+
+    @pytest.hookimpl(hookwrapper=True, tryfirst=True)
+    def pytest_runtest_protocol(self, item: Any, nextitem: Any):
+        if not self._is_instrumented or self._session_span is None:
+            yield
+            return
+
+        context_manager = None
+        state = None
+        try:
+            context_manager = self._tracer.start_as_current_span(
+                "pytest.test", kind=SpanKind.INTERNAL
+            )
+            span = context_manager.__enter__()
+            state = _TestState(span=span, context_manager=context_manager)
+            self._test_states[item.nodeid] = state
+            display_nodeid = self._test_nodeid(item)
+            self._set_common_attributes(
+                span,
+                log_type=TASK_LOG_TYPE,
+                entity_name=(
+                    getattr(item, "name", item.nodeid)
+                    if self._capture_content
+                    else display_nodeid.rsplit("::", 1)[-1]
+                ),
+                entity_path=display_nodeid,
+                input_payload=self._test_input(item),
+                worker_id=os.getenv("PYTEST_XDIST_WORKER"),
+            )
+        except Exception:
+            logger.exception("Failed to start Pytest test span for %s", item.nodeid)
+            if context_manager is not None:
+                context_manager.__exit__(None, None, None)
+            yield
+            return
+
+        try:
+            yield
+        finally:
+            try:
+                self._finish_test_span(item.nodeid, state)
+            except Exception:
+                logger.exception(
+                    "Failed to finish Pytest test span for %s", item.nodeid
+                )
+            finally:
+                self._test_states.pop(item.nodeid, None)
+                context_manager.__exit__(None, None, None)
+
+    @pytest.hookimpl(hookwrapper=True, trylast=True)
+    def pytest_runtest_makereport(self, item: Any, call: Any):
+        outcome = yield
+        state = self._test_states.get(item.nodeid)
+        if state is None:
+            return
+        try:
+            report = outcome.get_result()
+            state.reports[report.when] = report
+            state.durations[report.when] = float(getattr(report, "duration", 0.0))
+            if report.failed:
+                excinfo = getattr(call, "excinfo", None)
+                exception = getattr(excinfo, "value", None)
+                if isinstance(exception, BaseException):
+                    state.error = exception
+                    state.error_when = report.when
+                    if isinstance(exception, Exception) and self._capture_content:
+                        state.span.record_exception(exception)
+                    message = (
+                        str(exception)
+                        if self._capture_content
+                        else type(exception).__name__
+                    )
+                else:
+                    state.error_when = report.when
+                    message = "Pytest phase failed"
+                state.span.set_status(Status(StatusCode.ERROR, message))
+                state.span.set_attribute("status_code", 500)
+                state.span.set_attribute("error.message", message)
+        except Exception:
+            logger.exception("Failed to process Pytest report for %s", item.nodeid)
+
+    @staticmethod
+    def _test_outcome(state: _TestState) -> str:
+        if any(getattr(report, "failed", False) for report in state.reports.values()):
+            return "failed"
+        if any(getattr(report, "skipped", False) for report in state.reports.values()):
+            if any(hasattr(report, "wasxfail") for report in state.reports.values()):
+                return "xfailed"
+            return "skipped"
+        return "passed"
+
+    def _finish_test_span(self, nodeid: str, state: _TestState) -> None:
+        outcome = self._test_outcome(state)
+        self._outcome_counts[outcome] += 1
+        phases = {
+            phase: {
+                "outcome": getattr(report, "outcome", "unknown"),
+                "duration_seconds": state.durations.get(phase, 0.0),
+            }
+            for phase, report in state.reports.items()
+        }
+        output: dict[str, Any] = {
+            "outcome": outcome,
+            "phases": phases,
+            "duration_seconds": sum(state.durations.values()),
+            "content_captured": self._capture_content,
+        }
+        if state.error is not None:
+            error = {
+                "type": type(state.error).__name__,
+                "phase": state.error_when,
+            }
+            if self._capture_content:
+                error["message"] = str(state.error)
+            output["error"] = error
+        if outcome != "failed":
+            state.span.set_attribute("status_code", 200)
+        state.span.set_attribute(
+            SpanAttributes.TRACELOOP_ENTITY_OUTPUT,
+            _json_dumps(output, max_chars=self._max_attribute_chars),
+        )
+
+    def _finish_session_span(self, exitstatus: Any) -> None:
+        if self._session_span is None:
+            return
+        try:
+            numeric_status = int(exitstatus) if exitstatus is not None else None
+        except (TypeError, ValueError):
+            numeric_status = None
+        failed = numeric_status is not None and numeric_status not in {0, 5}
+        output = {
+            "exit_status": numeric_status,
+            "outcomes": dict(self._outcome_counts),
+            "total": sum(self._outcome_counts.values()),
+        }
+        self._session_span.set_attribute(
+            SpanAttributes.TRACELOOP_ENTITY_OUTPUT,
+            _json_dumps(output, max_chars=self._max_attribute_chars),
+        )
+        if failed:
+            message = f"Pytest exited with status {numeric_status}"
+            self._session_span.set_status(Status(StatusCode.ERROR, message))
+            self._session_span.set_attribute("status_code", 500)
+            self._session_span.set_attribute("error.message", message)
+        else:
+            self._session_span.set_attribute("status_code", 200)
+
+    def pytest_sessionfinish(self, session: Any, exitstatus: Any) -> None:
+        if self._session_context_manager is None:
+            return
+        try:
+            self._finish_session_span(exitstatus)
+        finally:
+            self._session_context_manager.__exit__(None, None, None)
+            self._session_context_manager = None
+            self._session_span = None
+            if self._telemetry is not None:
+                try:
+                    self._telemetry.flush()
+                except Exception:
+                    logger.debug("Failed to flush Pytest telemetry", exc_info=True)

respan_instrumentation_pytest-0.1.0/src/respan_instrumentation_pytest/plugin.py

@@ -0,0 +1,104 @@
+"""Pytest entry-point module for Respan test tracing."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from respan_instrumentation_pytest._constants import (
+    ENV_CAPTURE_CONTENT,
+    ENV_ENABLED,
+    ENV_WORKFLOW_NAME,
+    PYTEST_RUNTIME_PLUGIN_NAME,
+)
+from respan_instrumentation_pytest._runtime import PytestRuntimePlugin
+
+
+def _env_bool(name: str, default: bool) -> bool:
+    value = os.getenv(name)
+    if value is None:
+        return default
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def pytest_addoption(parser: Any) -> None:
+    group = parser.getgroup("respan")
+    group.addoption(
+        "--respan-tracing",
+        action="store_true",
+        default=None,
+        help="Emit Respan workflow/task spans for the Pytest session and tests.",
+    )
+    group.addoption(
+        "--respan-capture-content",
+        action="store_true",
+        dest="respan_capture_content",
+        default=None,
+        help="Capture test parameters and failure messages in Respan spans.",
+    )
+    group.addoption(
+        "--no-respan-capture-content",
+        action="store_false",
+        dest="respan_capture_content",
+        default=None,
+        help="Omit test parameters and failure messages from Respan spans.",
+    )
+    parser.addini(
+        "respan_tracing", "Enable Respan Pytest tracing.", type="bool", default=False
+    )
+    parser.addini(
+        "respan_capture_content",
+        "Capture test parameters and failure messages.",
+        type="bool",
+        default=True,
+    )
+    parser.addini(
+        "respan_workflow_name",
+        "Workflow name used for the Pytest session trace.",
+        default="",
+    )
+
+
+def _enabled(config: Any) -> bool:
+    cli_value = config.getoption("respan_tracing")
+    if cli_value is not None:
+        return bool(cli_value)
+    if _env_bool(ENV_ENABLED, False):
+        return True
+    return bool(config.getini("respan_tracing"))
+
+
+def _capture_content(config: Any) -> bool:
+    cli_value = config.getoption("respan_capture_content")
+    if cli_value is not None:
+        return bool(cli_value)
+    if os.getenv(ENV_CAPTURE_CONTENT) is not None:
+        return _env_bool(ENV_CAPTURE_CONTENT, True)
+    return bool(config.getini("respan_capture_content"))
+
+
+def _workflow_name(config: Any) -> str | None:
+    return os.getenv(ENV_WORKFLOW_NAME) or config.getini("respan_workflow_name") or None
+
+
+def pytest_configure(config: Any) -> None:
+    if not _enabled(config):
+        return
+    pluginmanager = config.pluginmanager
+    if pluginmanager.get_plugin(PYTEST_RUNTIME_PLUGIN_NAME) is not None:
+        return
+    instrumentor = PytestRuntimePlugin(
+        capture_content=_capture_content(config),
+        workflow_name=_workflow_name(config),
+    )
+    instrumentor.activate()
+    pluginmanager.register(instrumentor, PYTEST_RUNTIME_PLUGIN_NAME)
+
+
+def pytest_unconfigure(config: Any) -> None:
+    pluginmanager = config.pluginmanager
+    instrumentor = pluginmanager.get_plugin(PYTEST_RUNTIME_PLUGIN_NAME)
+    if instrumentor is None:
+        return
+    instrumentor.deactivate()
+    pluginmanager.unregister(instrumentor)