Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 46 additions & 0 deletions .github/workflows/attachments-python-tests.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
name: Python attachments

on:
pull_request:
paths:
- 'python/fi_instrumentation/**'
- 'python/traceai/**'
- 'python/tests/attachments/**'
- '.github/workflows/attachments-python-tests.yml'
push:
branches: [dev]
paths:
- 'python/fi_instrumentation/**'
- 'python/traceai/**'
- 'python/tests/attachments/**'
- '.github/workflows/attachments-python-tests.yml'

permissions:
contents: read

jobs:
component:
name: Attachments Python ${{ matrix.python }}
runs-on: ubuntu-24.04
timeout-minutes: 15
strategy:
fail-fast: false
matrix:
python: ['3.10', '3.11', '3.12', '3.13', '3.14']
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
with:
persist-credentials: false
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
with:
python-version: '${{ matrix.python }}'
- name: Install component dependencies
run: python -m pip install -e python 'pytest>=7,<8' 'pytest-asyncio>=0.21,<0.22' pytest-mock responses
- name: Run synthetic attachment, lifecycle exit-probe and auto tests
env:
PYTHONPATH: python
FI_BASE_URL: http://127.0.0.1:9
FI_GRPC_URL: http://127.0.0.1:9
# faulthandler dumps every thread's stack if a test stalls, so a hang
# is diagnosable from the log instead of only timing out the job.
run: python -m pytest -q -p no:cacheprovider -o faulthandler_timeout=120 python/tests/attachments python/traceai/tests
37 changes: 37 additions & 0 deletions python/fi_instrumentation/attachments/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
"""Opt-in, provider-owned attachments (audio, images, documents, files).

Capture is OFF by default and creating new recordings is separately OFF.
``create_attachment_manager`` returns a strict no-op null object when OFF: it
starts no thread or timer, registers no fork hook and imports neither the wire
adapter (``protocol``) nor ``jsonschema``. Importing an existing owned
recording never starts a recorder. RemoteUrl/ProviderFile/LocalFile are typed
but fail closed outside the completed-recording import seam.
"""

from ._disabled import DisabledAttachmentManager, OwnedRecordingHandle
from .admission import AdmissionTicket
from .errors import TransferError
from .imports import (
CompletedRecordingRequest, CompletedRecordingResolver, EgressOutputRegistry, EnvelopeSource, ImportHandle,
ProviderFileSource, ResolvedCompletedRecording, UnavailableResolver,
)
from .manager import AttachmentManager, AttachmentSpanProcessor, create_attachment_manager
from .policy import AttachmentConfig, AttachmentPolicy, CapturePolicy, ServerPolicy
from .recording import PcmFormat, RecordingOptions, RecordingResult, RecordingStatus, RecordingWriter, TrackSpec
from .sources import FileIdentity, OwnedRecordingFile, RecordingFileScope
from .stream import AttachmentStream, StreamOptions
from .types import (
AttachmentHandle, AttachmentStatus, Bytes, Completion, CorrelationHandle, FlushResult,
LocalFile, ProviderFile, RemoteUrl,
)

__all__ = [
"AdmissionTicket", "AttachmentConfig", "AttachmentHandle", "AttachmentManager", "AttachmentPolicy",
"AttachmentSpanProcessor", "AttachmentStatus", "AttachmentStream", "Bytes", "CapturePolicy", "Completion",
"CompletedRecordingRequest", "CompletedRecordingResolver", "CorrelationHandle", "DisabledAttachmentManager",
"EgressOutputRegistry", "EnvelopeSource", "FileIdentity", "FlushResult", "ImportHandle", "LocalFile",
"OwnedRecordingFile", "OwnedRecordingHandle", "PcmFormat", "ProviderFile", "ProviderFileSource",
"RecordingFileScope", "RecordingOptions", "RecordingResult", "RecordingStatus", "RecordingWriter", "RemoteUrl",
"ResolvedCompletedRecording", "ServerPolicy", "StreamOptions", "TrackSpec", "TransferError",
"UnavailableResolver", "create_attachment_manager",
]
129 changes: 129 additions & 0 deletions python/fi_instrumentation/attachments/_disabled.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,129 @@
"""The disabled null object (design 8.1) and shared light handle types.

When attachments are OFF nothing here starts a thread or timer, registers a
fork/atexit hook, imports the wire adapter or ``jsonschema``, re-reads the
environment, or writes span attributes. Every call returns immediately.
"""

import asyncio
import threading
from typing import Optional

from .admission import AdmissionTicket
from .imports import ImportHandle
from .policy import AttachmentConfig, AttachmentPolicy
from .recording import RecordingWriter
from .stream import AttachmentStream
from .types import AttachmentHandle, AttachmentStatus, Completion, FlushResult


class OwnedRecordingHandle:
"""Result of ``attach_owned_recording``: tier ``single``, ``wav_recording`` or ``denied``."""

def __init__(self, tier: str, reason: str, *, handle: Optional[AttachmentHandle] = None,
recording_id: Optional[str] = None, manager=None):
self.tier = tier
self.reason = reason
self.recording_id = recording_id if tier == "wav_recording" else None
self._handle = handle
self._manager = manager
self._job = None
self._event = threading.Event()
self._completion: Optional[Completion] = None
if tier == "denied" or (handle is None and reason != "queued"):
self._finish(reason)

def _finish(self, status: str) -> None:
if not self._event.is_set():
self._completion = Completion(status)
self._event.set()

def result(self, timeout: float = 0) -> Completion:
if self._handle is not None:
return self._handle.result(timeout)
if timeout and timeout > 0:
self._event.wait(min(timeout, 30))
return self._completion or Completion("unfinished")

async def wait(self, timeout: float = 30.0) -> Completion:
if self._handle is not None:
return await self._handle.wait(timeout)
if self._event.is_set():
return self._completion
return await asyncio.to_thread(self.result, timeout)

def cancel(self) -> None:
if self._manager is None:
return
if self._handle is not None:
self._manager.cancel(self._handle)
elif self._job is not None:
self._job.cancelled = True
self._manager.cancel(self)

def __repr__(self) -> str:
return "OwnedRecordingHandle(tier=%r, reason=%r)" % (self.tier, self.reason)


_EMPTY = FlushResult(0, 0)


class DisabledAttachmentManager:
"""Full public surface; every call is inert and returns ``disabled``."""

capture_session_id = None
correlation_nonce = None

def __init__(self, *, config: Optional[AttachmentConfig] = None, trace_config=None):
self.config = config or AttachmentConfig(enabled=False)
self.policy = AttachmentPolicy(self.config, trace_config)

def status(self) -> AttachmentStatus:
return AttachmentStatus("disabled")

@property
def owned_bytes(self) -> int:
return 0

def ready(self, timeout: float = 5) -> bool:
return False

async def ready_async(self, timeout: float = 5) -> bool:
return False

def preflight(self, target=None, **_options) -> AdmissionTicket:
return AdmissionTicket(None, "disabled")

def attach(self, span_or_context=None, source=None, **_options) -> AttachmentHandle:
return AttachmentHandle("disabled")

def start_attachment_stream(self, target=None, options=None) -> AttachmentStream:
return AttachmentStream.denied("disabled")

def start_recording(self, target=None, options=None) -> RecordingWriter:
return RecordingWriter(reason="disabled")

def attach_owned_recording(self, target=None, source=None, **_options) -> OwnedRecordingHandle:
return OwnedRecordingHandle("denied", "disabled")

async def import_completed_recording(self, target=None, request=None, **_options) -> ImportHandle:
# The resolver is never called.
return ImportHandle("disabled")

def update_policy(self, server) -> None:
return None

def cancel(self, handle) -> None:
return None

def flush(self, timeout: float = 5) -> FlushResult:
return _EMPTY

async def flush_async(self, timeout: float = 5) -> FlushResult:
return _EMPTY

def shutdown(self, timeout: Optional[float] = None) -> FlushResult:
return _EMPTY

def __repr__(self) -> str:
return "DisabledAttachmentManager()"
Loading
Loading