Skip to content

Auto Trace

Metaclass for automatic method tracing via OpenTelemetry.

Classes

AutoTracedMeta

Bases: type

Metaclass that automatically applies @traced_and_logged to all public methods.

This enables automatic OpenTelemetry span creation and debug logging for all method calls on classes using this metaclass.

Control via environment variable

FLOCK_AUTO_TRACE=true - Enable auto-tracing (default) FLOCK_AUTO_TRACE=false - Disable auto-tracing

Example

class Agent(metaclass=AutoTracedMeta): def execute(self, ctx, artifacts): # Automatically traced and logged ...

Functions

__new__ 
__new__(mcs, name, bases, namespace, **kwargs)

Create a new class with auto-traced methods.

Source code in src/flock/logging/auto_trace.py 
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
def __new__(mcs, name, bases, namespace, **kwargs):
    """Create a new class with auto-traced methods."""
    if not ENABLE_AUTO_TRACE:
        # If auto-tracing is disabled, return the class unchanged
        return super().__new__(mcs, name, bases, namespace, **kwargs)

    # Apply @traced_and_logged to all public methods
    for attr_name, attr_value in list(namespace.items()):
        # Skip private methods (starting with _)
        if attr_name.startswith("_"):
            continue

        # Skip non-callables
        if not callable(attr_value):
            continue

        # Skip if already traced
        if getattr(attr_value, "_traced", False):
            continue

        # Skip if explicitly marked to skip tracing
        if getattr(attr_value, "_skip_trace", False):
            continue

        # Apply the decorator
        traced_func = traced_and_logged(attr_value)
        traced_func._traced = True  # Mark as traced to avoid double-wrapping
        namespace[attr_name] = traced_func

    return super().__new__(mcs, name, bases, namespace, **kwargs)

Functions

skip_trace 

skip_trace(func)

Decorator to mark a method to skip auto-tracing.

Use this for methods that are called very frequently or are not interesting for debugging purposes.

Example

class Agent(metaclass=AutoTracedMeta): @skip_trace def _internal_helper(self): # Not traced ...

Source code in src/flock/logging/auto_trace.py 
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
def skip_trace(func):
    """Decorator to mark a method to skip auto-tracing.

    Use this for methods that are called very frequently or are not
    interesting for debugging purposes.

    Example:
        class Agent(metaclass=AutoTracedMeta):
            @skip_trace
            def _internal_helper(self):
                # Not traced
                ...
    """
    func._skip_trace = True
    return func