diff --git a/solarwinds_apm/w3c_transformer.py b/solarwinds_apm/w3c_transformer.py index a3b71f48c..0b21f820e 100644 --- a/solarwinds_apm/w3c_transformer.py +++ b/solarwinds_apm/w3c_transformer.py @@ -13,7 +13,7 @@ class W3CTransformer: - """Transforms inputs to W3C-compliant data for SolarWinds context propagation""" + """Transform inputs to W3C-compliant data for SolarWinds context propagation.""" _DECISION = "{}" _SPAN_ID_HEX = "{:016x}" @@ -23,23 +23,54 @@ class W3CTransformer: @classmethod def span_id_from_int(cls, span_id: int) -> str: - """Formats span ID as 16-byte hexadecimal string""" + """ + Format span ID as 16-byte hexadecimal string. + + Parameters: + span_id (int): The span ID as an integer. + + Returns: + str: The span ID formatted as 16-character hexadecimal string. + """ return cls._SPAN_ID_HEX.format(span_id) @classmethod def span_id_from_sw(cls, sw_val: str) -> str: - """Formats span ID from sw tracestate value""" + """ + Extract span ID from sw tracestate value. + + Parameters: + sw_val (str): The sw tracestate value (format: "-"). + + Returns: + str: The span ID portion of the sw value. + """ return sw_val.split("-")[0] @classmethod def trace_flags_from_int(cls, trace_flags: int) -> str: - """Formats trace flags as 8-bit field""" + """ + Format trace flags as 8-bit hexadecimal field. + + Parameters: + trace_flags (int): The trace flags as an integer. + + Returns: + str: The trace flags formatted as 2-character hexadecimal string. + """ return cls._TRACE_FLAGS_HEX.format(trace_flags) @classmethod def traceparent_from_context(cls, span_context: SpanContext) -> str: - """Maps a liboboe W3C compatible trace_context from - provided OTel span context.""" + """ + Create W3C traceparent header from OpenTelemetry span context. + + Parameters: + span_context (SpanContext): The OpenTelemetry span context. + + Returns: + str: W3C traceparent header value (format: "00---"). + """ template = "-".join( [ cls._VERSION, @@ -57,31 +88,62 @@ def traceparent_from_context(cls, span_context: SpanContext) -> str: @classmethod def sw_from_context(cls, span_context: SpanContext) -> str: - """Formats tracestate sw value from SpanContext as 16-byte span_id - with 8-bit trace_flags. + """ + Format tracestate sw value from SpanContext. - Example: 1a2b3c4d5e6f7g8h-01""" + Creates sw value as 16-byte span_id with 8-bit trace_flags. + + Parameters: + span_context (SpanContext): The OpenTelemetry span context. + + Returns: + str: SW tracestate value (format: "-", e.g., "1a2b3c4d5e6f7g8h-01"). + """ sw = "-".join([cls._SPAN_ID_HEX, cls._TRACE_FLAGS_HEX]) return sw.format(span_context.span_id, span_context.trace_flags) @classmethod def trace_and_span_id_from_context(cls, span_context: SpanContext) -> str: - """Formats trace ID and span ID as 32-byte and 16-byte hex str, respectively""" + """ + Format trace ID and span ID as hexadecimal strings. + + Parameters: + span_context (SpanContext): The OpenTelemetry span context. + + Returns: + str: Trace and span IDs (format: "<32-byte-trace-id>-<16-byte-span-id>"). + """ trace_span = "-".join([cls._TRACE_ID_HEX, cls._SPAN_ID_HEX]) return trace_span.format(span_context.trace_id, span_context.span_id) @classmethod def sw_from_span_and_decision(cls, span_id: int, decision: str) -> str: - """Formats tracestate sw value from span_id and liboboe decision - as 16-byte span_id with 8-bit trace_flags. + """ + Format tracestate sw value from span_id and liboboe decision. - Example: 1a2b3c4d5e6f7g8h-01""" + Creates sw value as 16-byte span_id with 8-bit trace_flags. + + Parameters: + span_id (int): The span ID as an integer. + decision (str): The liboboe sampling decision. + + Returns: + str: SW tracestate value (format: "-", e.g., "1a2b3c4d5e6f7g8h-01"). + """ sw = "-".join([cls._SPAN_ID_HEX, cls._DECISION]) return sw.format(span_id, decision) @classmethod def remove_response_from_sw(cls, trace_state: TraceState) -> TraceState: - """Remove xtraceoptions response from tracestate""" + """ + Remove xtraceoptions response from tracestate. + + Parameters: + trace_state (TraceState): The tracestate to modify. + + Returns: + TraceState: Modified tracestate with xtraceoptions response removed. + """ if trace_state.get(INTL_SWO_X_OPTIONS_RESPONSE_KEY): trace_state = trace_state.delete(INTL_SWO_X_OPTIONS_RESPONSE_KEY) return trace_state