diff --git a/solarwinds_apm/propagator.py b/solarwinds_apm/propagator.py index 7e358746e..5153feb2f 100644 --- a/solarwinds_apm/propagator.py +++ b/solarwinds_apm/propagator.py @@ -29,9 +29,7 @@ class SolarWindsPropagator(TraceContextTextMapPropagator): - """Extracts and injects SolarWinds headers and W3C trace context - headers for trace propagation. - """ + """Extract and inject SolarWinds headers and W3C trace context for trace propagation.""" _INVALID_SPAN_ID = 0x0000000000000000 _TRACESTATE_HEADER_NAME = "tracestate" @@ -44,8 +42,15 @@ def extract( context: Context | None = None, getter: textmap.Getter = textmap.default_getter, ) -> Context: - """Extracts traceparent, tracestate, sw trace options, and signature - from carrier into OTel Context. + """Extract traceparent, tracestate, sw trace options, and signature from carrier into OTel Context. + + Parameters: + carrier (textmap.CarrierT): The carrier to extract context from. + context (Context | None): Optional existing context to update. Defaults to None. + getter (textmap.Getter): Getter for extracting headers from carrier. Defaults to default_getter. + + Returns: + Context: Updated context with extracted trace information. """ context = super().extract(carrier, context, getter) @@ -69,9 +74,14 @@ def inject( context: Context | None = None, setter: textmap.Setter = textmap.default_setter, ) -> None: - """Injects traceparent, tracestate with valid sw into carrier - for HTTP request. Excludes any xtraceoptions_response if in - tracestate. + """Inject traceparent and tracestate with valid sw into carrier for HTTP request. + + Excludes any xtraceoptions_response if in tracestate. + + Parameters: + carrier (textmap.CarrierT): The carrier to inject context into. + context (Context | None): Optional context to inject from. Defaults to None. + setter (textmap.Setter): Setter for injecting headers into carrier. Defaults to default_setter. """ super().inject(carrier, context, setter) @@ -130,5 +140,10 @@ def inject( def fields( self, ) -> typing.Set[str]: # pylint: disable=deprecated-typing-alias - """Returns a set with the fields set in `inject`""" + """ + Return the set of fields injected by this propagator. + + Returns: + typing.Set[str]: Set of header field names. + """ return super().fields diff --git a/solarwinds_apm/response_propagator.py b/solarwinds_apm/response_propagator.py index a7df2429d..63379c0a4 100644 --- a/solarwinds_apm/response_propagator.py +++ b/solarwinds_apm/response_propagator.py @@ -28,7 +28,7 @@ class SolarWindsTraceResponsePropagator(ResponsePropagator): - """Propagator that injects SW values into HTTP responses""" + """Inject SolarWinds trace values into HTTP responses.""" _HTTP_HEADER_ACCESS_CONTROL_EXPOSE_HEADERS = ( "Access-Control-Expose-Headers" @@ -42,7 +42,13 @@ def inject( context: Context | None = None, setter: textmap.Setter = textmap.default_setter, ) -> None: - """Injects x-trace and options-response into the HTTP response carrier.""" + """Inject x-trace and options-response into the HTTP response carrier. + + Parameters: + carrier (textmap.CarrierT): The HTTP response carrier to inject headers into. + context (Context | None): Optional context to inject from. Defaults to None. + setter (textmap.Setter): Setter for injecting headers into carrier. Defaults to default_setter. + """ span = trace.get_current_span(context) span_context = span.get_span_context() if span_context == trace.INVALID_SPAN_CONTEXT: @@ -75,10 +81,18 @@ def inject( ) def recover_response_from_tracestate(self, tracestate: TraceState) -> str: - """Use tracestate to recover xtraceoptions response by - converting delimiters: + """ + Recover xtraceoptions response from tracestate by converting delimiters. + + Converts W3C-sanitized delimiters back to original format: EQUALS_W3C_SANITIZED becomes EQUALS COMMA_W3C_SANITIZED becomes COMMA + + Parameters: + tracestate (TraceState): The tracestate to extract response from. + + Returns: + str: The recovered xtraceoptions response string. """ sanitized = tracestate.get(INTL_SWO_X_OPTIONS_RESPONSE_KEY, None) if not sanitized: diff --git a/solarwinds_apm/sampler.py b/solarwinds_apm/sampler.py index f6a43744c..0115adae9 100644 --- a/solarwinds_apm/sampler.py +++ b/solarwinds_apm/sampler.py @@ -21,21 +21,25 @@ class ParentBasedSwSampler(ParentBased): - """ - Sampler that respects its parent span's sampling decision, but otherwise - samples according to the configurations from the NH/AO backend. + """Respect parent span's sampling decision or use SolarWinds backend configuration. - Requires "SolarWindsApmConfig". + Requires SolarWindsApmConfig. """ def __init__( self, apm_config: SolarWindsApmConfig, - ): + ) -> None: """ + Initialize ParentBasedSwSampler with SolarWinds APM configuration. + + Uses HttpSampler for non-Lambda environments or JsonSampler for Lambda. Uses HttpSampler/JsonSampler if no parent span. Uses HttpSampler/JsonSampler if parent span is_remote. - Uses OTEL defaults if parent span is_local. + Uses OpenTelemetry defaults if parent span is_local. + + Parameters: + apm_config (SolarWindsApmConfig): The SolarWinds APM configuration. """ configuration = SolarWindsApmConfig.to_configuration(apm_config) self.sampler = None @@ -58,7 +62,12 @@ def __init__( # should_sample defined by ParentBased def wait_until_ready(self, timeout: int) -> bool: - """ - Waits until the sampler is ready. + """Wait until the sampler is ready. + + Parameters: + timeout (int): Maximum time to wait in seconds. + + Returns: + bool: True if sampler is ready, False if timeout occurred. """ return self.sampler.wait_until_ready(timeout) diff --git a/solarwinds_apm/traceoptions.py b/solarwinds_apm/traceoptions.py index bf7b6a7d9..c1e0d0919 100644 --- a/solarwinds_apm/traceoptions.py +++ b/solarwinds_apm/traceoptions.py @@ -4,6 +4,8 @@ # # Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. +"""X-Trace-Options header parsing and formatting for trigger tracing.""" + import logging import re @@ -11,7 +13,10 @@ class XTraceOptions: - """Formats X-Trace-Options and signature for trigger tracing""" + """Parse and format X-Trace-Options and signature headers for trigger tracing. + + Handles parsing of trigger-trace, sw-keys, custom-*, and ts options. + """ _XTRACEOPTIONS_CUSTOM = r"^custom-[^\s]*$" _XTRACEOPTIONS_CUSTOM_RE = re.compile(_XTRACEOPTIONS_CUSTOM) @@ -25,11 +30,13 @@ def __init__( self, xtraceoptions_header: str = "", signature_header: str = "", - ): + ) -> None: """ - Args: - xtraceoptions_header: extracted request header value - signature_header: extracted request header value + Initialize XTraceOptions from request headers. + + Parameters: + xtraceoptions_header (str): X-Trace-Options header value. Defaults to "". + signature_header (str): X-Trace-Options-Signature header value. Defaults to "". """ self.ignored = [] self.options_header = ""