gAITdZddlmZddlZddlmZmZddlZddlm Z ddl m Z m Z m Z mZddlmZddlmZmZmZdd lmZdd lmZdd lmZdd lmZdd lmZddlm Z ddl!m"Z"m#Z#m$Z$e"dZ%ejLe'Z(GddeZ)GddejTZ+dZ,dZ-y)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_HTTPStabilityMode)_OpenTelemetrySemanticConventionStability!_OpenTelemetryStabilitySignalType)OpenTelemetryMiddleware)ClientRequestHookClientResponseHookServerRequestHook _instruments) __version__)BaseInstrumentor) get_meter)SpanAttributes) get_tracer)get_excluded_urlsparse_excluded_urlssanitize_methodFASTAPIc|eZdZdZdZe d d dZed dZd dZdZ dZ y) FastAPIInstrumentorz$7$7%94W5Y5Y+  59C 1.III$??CCCHJ OOQ c|jDcgc]}|jtur|c}|_|j|_d|_ycc}w)NF)user_middlewareclsr build_middleware_stackmiddleware_stackr)r:xs r>uninstrument_appz$FastAPIInstrumentor.uninstrument_app2sW(( (uu33 (  #99;05-  sActSNrselfs r>instrumentation_dependenciesz0FastAPIInstrumentor.instrumentation_dependencies<sr@c ztj|_|jdt_|jdt_|jdt_|jdt_|jdt_ |jdt_ |jdt_ |jd}|tn t|t_|jd t_|jd t_tt_y) Nr;r#r$r%r(r)r*r!r<r+)fastapiFastAPI_original_fastapigetr5_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_fieldsr1r_excluded_urls_meter_provider_exclude_spans)rKkwargsrYs r> _instrumentzFastAPIInstrumentor._instrument?s!(06 ;L0M-4:JJ !5 15;JJ !5 16 B JJ= > B O4% $$^4 + 06zz:J/K,.4jj.I+.r@c tjD]}|j|tjj|jt _yrI)r5r6rGclearrPrNrO)rKr\instances r> _uninstrumentz!FastAPIInstrumentor._uninstrument^s@,GGH  ! !( +H77==?00r@) NNNNNNNNNN)r#rr$r r%r r(list[str] | Noner)rbr*rbr+z'list[Literal['receive', 'send']] | None)r:zfastapi.FastAPI)returnzCollection[str]) r2 __module__ __qualname____doc__rP staticmethodr?rGrLr]rar@r>rrs 261537@DAEAEAEP.P/P1 P.>P/?P/?P?PPd66/>1r@rceZdZUdZdZdZdZded<dZded<dZ ded<e Z e jZfdZd ZxZS) r5NrrSr rTr rUct||i|tttt j tt j}tttt jtt j}|jtt jtt jt j t j"||t j$t j&t j(t j* d|_t j.j1|y)Nrr T)super__init__rr2rr5rRr_sem_conv_opt_in_moderrZr3r rYr4rSrTrUrVrWrXr[rr6r7)rKargsr\r&r' __class__s r>rlz_InstrumentedFastAPI.__init__os $)&)   1 1&$::     0 0&$::    #.==!: 4 I I 4 I I!5!K!K0D0i0i1E1k1k1E1k1k.==  26.77;;DAr@ch|tjvr tjj|yyrI)r5r6removerJs r>__del__z_InstrumentedFastAPI.__del__s+ 'BB B ; ; B B4 H Cr@)r2rdrerRrZrYrS__annotations__rTrUsetr6rDEFAULTrmrlrr __classcell__)ros@r>r5r5esXON.2+2.2+204-4!$.66"BHIr@r5c|d}d}|jD]X}|j|\}}|tjk(r|j}|S|tj k(sM|j}Z|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 r:N)routesmatchesrFULLpathPARTIAL)scoper:routestarlette_routematch_s r>_get_route_detailsrsu ,C E::"**51q EJJ #((E  L EMM !#((E & Lr@ct|}t|jddj}i}|dk(rd}|r||tj <|r |r |d|}||fS|r|}||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_OTHERr0 )rrrQstripr HTTP_ROUTE)r}r~r attributes span_names r>r4r4s u %E UYYx4::< =FJ  05 >,,- %haw' j    j   j  r@).rf __future__rloggingtypingrrrNstarlette.routingr&opentelemetry.instrumentation._semconvrrr r "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.httprrrr1 getLoggerr2r8rrOr5rr4rhr@r>rsbH#&# G GEG+6* ,I6 '  H %K1*K1\0I7??0If4!r@