o g9I@sdZddlmZddlZddlmZmZddlZddlm Z ddl m Z m Z m Z mZddlmZddlmZmZmZdd lmZdd lmZdd lmZdd lmZdd lmZddlm Z ddl!m"Z"m#Z#m$Z$e"dZ%e&e'Z(GdddeZ)Gdddej*Z+ddZ,ddZ-dS)a Usage ----- .. code-block:: python import fastapi from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor app = fastapi.FastAPI() @app.get("/foobar") async def foobar(): return {"message": "hello world"} FastAPIInstrumentor.instrument_app(app) Configuration ------------- Exclude lists ************* To exclude certain URLs from tracking, set the environment variable ``OTEL_PYTHON_FASTAPI_EXCLUDED_URLS`` (or ``OTEL_PYTHON_EXCLUDED_URLS`` to cover all instrumentations) to a string of comma delimited regexes that match the URLs. For example, :: export OTEL_PYTHON_FASTAPI_EXCLUDED_URLS="client/.*/info,healthcheck" will exclude requests such as ``https://site/client/123/info`` and ``https://site/xyz/healthcheck``. You can also pass comma delimited regexes directly to the ``instrument_app`` method: .. code-block:: python FastAPIInstrumentor.instrument_app(app, excluded_urls="client/.*/info,healthcheck") Request/Response hooks ********************** This instrumentation supports request and response hooks. These are functions that get called right after a span is created for a request and right before the span is finished for the response. - The server request hook is passed a server span and ASGI scope object for every incoming request. - The client request hook is called with the internal span, and ASGI scope and event when the method ``receive`` is called. - The client response hook is called with the internal span, and ASGI scope and event when the method ``send`` is called. .. code-block:: python def server_request_hook(span: Span, scope: dict[str, Any]): if span and span.is_recording(): span.set_attribute("custom_user_attribute_from_request_hook", "some-value") def client_request_hook(span: Span, scope: dict[str, Any], message: dict[str, Any]): if span and span.is_recording(): span.set_attribute("custom_user_attribute_from_client_request_hook", "some-value") def client_response_hook(span: Span, scope: dict[str, Any], message: dict[str, Any]): if span and span.is_recording(): span.set_attribute("custom_user_attribute_from_response_hook", "some-value") FastAPIInstrumentor().instrument(server_request_hook=server_request_hook, client_request_hook=client_request_hook, client_response_hook=client_response_hook) Capture HTTP request and response headers ***************************************** You can configure the agent to capture specified HTTP headers as span attributes, according to the `semantic convention `_. Request headers *************** To capture HTTP request headers as span attributes, set the environment variable ``OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST`` to a comma delimited list of HTTP header names, or pass the ``http_capture_headers_server_request`` keyword argument to the ``instrument_app`` method. For example using the environment variable, :: export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST="content-type,custom_request_header" will extract ``content-type`` and ``custom_request_header`` from the request headers and add them as span attributes. Request header names in FastAPI are case-insensitive. So, giving the header name as ``CUStom-Header`` in the environment variable will capture the header named ``custom-header``. Regular expressions may also be used to match multiple headers that correspond to the given pattern. For example: :: export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST="Accept.*,X-.*" Would match all request headers that start with ``Accept`` and ``X-``. To capture all request headers, set ``OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST`` to ``".*"``. :: export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST=".*" The name of the added span attribute will follow the format ``http.request.header.`` where ```` is the normalized HTTP header name (lowercase, with ``-`` replaced by ``_``). The value of the attribute will be a single item list containing all the header values. For example: ``http.request.header.custom_request_header = ["", ""]`` Response headers **************** To capture HTTP response headers as span attributes, set the environment variable ``OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE`` to a comma delimited list of HTTP header names, or pass the ``http_capture_headers_server_response`` keyword argument to the ``instrument_app`` method. For example using the environment variable, :: export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE="content-type,custom_response_header" will extract ``content-type`` and ``custom_response_header`` from the response headers and add them as span attributes. Response header names in FastAPI are case-insensitive. So, giving the header name as ``CUStom-Header`` in the environment variable will capture the header named ``custom-header``. Regular expressions may also be used to match multiple headers that correspond to the given pattern. For example: :: export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE="Content.*,X-.*" Would match all response headers that start with ``Content`` and ``X-``. To capture all response headers, set ``OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE`` to ``".*"``. :: export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE=".*" The name of the added span attribute will follow the format ``http.response.header.`` where ```` is the normalized HTTP header name (lowercase, with ``-`` replaced by ``_``). The value of the attribute will be a list containing the header values. For example: ``http.response.header.custom_response_header = ["", ""]`` Sanitizing headers ****************** In order to prevent storing sensitive data such as personally identifiable information (PII), session keys, passwords, etc, set the environment variable ``OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SANITIZE_FIELDS`` to a comma delimited list of HTTP header names to be sanitized, or pass the ``http_capture_headers_sanitize_fields`` keyword argument to the ``instrument_app`` method. Regexes may be used, and all header names will be matched in a case-insensitive manner. For example using the environment variable, :: export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SANITIZE_FIELDS=".*session.*,set-cookie" will replace the value of headers such as ``session-id`` and ``set-cookie`` with ``[REDACTED]`` in the span. Note: The environment variable names used to capture HTTP headers are still experimental, and thus are subject to change. API --- ) annotationsN) CollectionLiteral)Match)_get_schema_url)_OpenTelemetrySemanticConventionStability!_OpenTelemetryStabilitySignalType_StabilityMode)OpenTelemetryMiddleware)ClientRequestHookClientResponseHookServerRequestHook _instruments) __version__)BaseInstrumentor) get_meter)SpanAttributes) get_tracer)get_excluded_urlsparse_excluded_urlssanitize_methodFASTAPIc@s`eZdZdZdZe          ddddZedddZd ddZddZ ddZ dS)!FastAPIInstrumentorz 4s  z8FastAPIInstrumentor.uninstrument_app..F)user_middlewarebuild_middleware_stackmiddleware_stackr#)r9r=r=r>uninstrument_app2s   z$FastAPIInstrumentor.uninstrument_appreturnCollection[str]cCstSNrselfr=r=r>instrumentation_dependencies<sz0FastAPIInstrumentor.instrumentation_dependenciescKstj|_|dt_|dt_|dt_|dt_|dt_ |dt_ |dt_ |d}|dur9t nt |t_|d t_|d t_tt_dS) Nr:rrrrrr r'r;r!)fastapiFastAPI_original_fastapigetr4_tracer_provider_server_request_hook_client_request_hook_client_response_hook$_http_capture_headers_server_request%_http_capture_headers_server_response%_http_capture_headers_sanitize_fieldsr0r_excluded_urls_meter_provider_exclude_spans)rMkwargsrZr=r=r> _instrument?s4     zFastAPIInstrumentor._instrumentcKs,tjD]}||qtj|jt_dSrK)r4r5rHclearrQrOrP)rMr]instancer=r=r> _uninstrument^s    z!FastAPIInstrumentor._uninstrument) NNNNNNNNNN)rr rr rr rrrrr rr!r")r9r@)rIrJ) r1 __module__ __qualname____doc__rQ staticmethodr?rHrNr^rar=r=r=r>rs(R   rcsbeZdZUdZdZdZdZded<dZded<dZ ded<e Z e j Zfdd Zd d ZZS) r4Nr rTr rUr rVcstj|i|ttttjttjd}t tttj ttjd}|j t tj ttjtjtj||tjtjtjtjd d|_tj|dS)Nr$r&T)super__init__rr1rr4rSr_sem_conv_opt_in_moderr[r2r rZr3rTrUrVrWrXrYr\r#r5r6)rMargsr]r)r* __class__r=r>rgosBz_InstrumentedFastAPI.__init__cCs|tjvr tj|dSdSrK)r4r5removerLr=r=r>__del__s z_InstrumentedFastAPI.__del__)r1rbrcrSr[rZrT__annotations__rUrVsetr5r DEFAULTrhrgrm __classcell__r=r=rjr>r4es     $r4cCsP|d}d}|jD]}||\}}|tjkr|j}|S|tjkr%|j}q |S)a@ Function to retrieve Starlette route from scope. TODO: there is currently no way to retrieve http.route from a starlette application from scope. See: https://github.com/encode/starlette/pull/804 Args: scope: A Starlette scope Returns: A string containing the route or None r9N)routesmatchesrFULLpathPARTIAL)scoper9routestarlette_routematch_r=r=r>_get_route_detailss    r|cCstt|}t|dd}i}|dkrd}|r||tj<|r,|r,|d|}||fS|r4|}||fS|}||fS)z Callback to retrieve span name and attributes from scope. Args: scope: A Starlette scope Returns: A tuple of span name and attributes method_OTHERr/ )r|rrRstripr HTTP_ROUTE)rwrxr} attributes span_namer=r=r>r3s  r3).rd __future__rloggingtypingrrrOstarlette.routingr&opentelemetry.instrumentation._semconvrrrr "opentelemetry.instrumentation.asgir (opentelemetry.instrumentation.asgi.typesr r r -opentelemetry.instrumentation.fastapi.packager-opentelemetry.instrumentation.fastapi.versionr*opentelemetry.instrumentation.instrumentorropentelemetry.metricsropentelemetry.semconv.traceropentelemetry.traceropentelemetry.util.httprrrr0 getLoggerr1r7rrPr4r|r3r=r=r=r>s0 %         3