Method start_trace

agentops/sdk/core.py:381–428

Starts a new trace (root span) and returns its context. Args: trace_name: Name for the trace (e.g., "session", "my_custom_trace"). tags: Optional tags to attach to the trace span. is_init_trace: Internal flag to mark if this is the automatically

(
        self, trace_name: str = "session", tags: Optional[dict | list] = None, is_init_trace: bool = False
    )

        # No need to register them here anymore

    def start_trace(
        self, trace_name: str = "session", tags: Optional[dict | list] = None, is_init_trace: bool = False
    ) -> Optional[TraceContext]:
        """
        Starts a new trace (root span) and returns its context.

        Args:
            trace_name: Name for the trace (e.g., "session", "my_custom_trace").
            tags: Optional tags to attach to the trace span.
            is_init_trace: Internal flag to mark if this is the automatically started init trace.

        Returns:
            A TraceContext object containing the span and context token, or None if not initialized.
        """
        if not self.initialized:
            logger.warning("Global tracer not initialized. Cannot start trace.")
            return None

        # Build trace attributes
        attributes = get_trace_attributes(tags=tags)
        # Include system metadata only for the default session trace
        if trace_name == "session":
            attributes.update(get_system_resource_attributes())

        # make_span creates and starts the span, and activates it in the current context
        # It returns: span, context_object, context_token
        span, _, context_token = self.make_span(trace_name, span_kind=SpanKind.SESSION, attributes=attributes)
        logger.debug(f"Trace '{trace_name}' started with span ID: {span.get_span_context().span_id}")

        # Log the session replay URL for this new trace
        try:
            log_trace_url(span, title=trace_name)
        except Exception as e:
            logger.warning(f"Failed to log trace URL for '{trace_name}': {e}")

        trace_context = TraceContext(span, token=context_token, is_init_trace=is_init_trace)

        # Track the active trace
        with self._traces_lock:
            try:
                trace_id = f"{span.get_span_context().trace_id:x}"
            except (TypeError, ValueError):
                # Handle case where span is mocked or trace_id is not a valid integer
                trace_id = str(span.get_span_context().trace_id)
            self._active_traces[trace_id] = trace_context
            logger.debug(f"Added trace {trace_id} to active traces. Total active: {len(self._active_traces)}")

        return trace_context

    def end_trace(
        self, trace_context: Optional[TraceContext] = None, end_state: Union[Any, StatusCode, str] = None