diff --git a/docs/integrations/asgi.md b/docs/integrations/asgi.md index a77f3ba1..1ff95e67 100644 --- a/docs/integrations/asgi.md +++ b/docs/integrations/asgi.md @@ -44,6 +44,11 @@ if __name__ == "__main__": You can read more about the OpenTelemetry ASGI middleware [here][opentelemetry-asgi]. +## Excluding URLs from instrumentation + + +- [Quick guide](use-cases/web-frameworks.md#excluding-urls-from-instrumentation) + ## Capturing request and response headers diff --git a/docs/integrations/django.md b/docs/integrations/django.md index fd0f1b39..76d7a184 100644 --- a/docs/integrations/django.md +++ b/docs/integrations/django.md @@ -26,6 +26,12 @@ logfire.instrument_django() **OpenTelemetry Django Instrumentation** package, which you can find more information about [here][opentelemetry-django]. +## Excluding URLs from instrumentation + + +- [Quick guide](use-cases/web-frameworks.md#excluding-urls-from-instrumentation) +- [OpenTelemetry Documentation](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/django/django.html#exclude-lists) + ## Capturing request and response headers diff --git a/docs/integrations/fastapi.md b/docs/integrations/fastapi.md index fb2e0319..c36e4234 100644 --- a/docs/integrations/fastapi.md +++ b/docs/integrations/fastapi.md @@ -95,12 +95,10 @@ logfire.instrument_fastapi(app, request_attributes_mapper=request_attributes_map contents of `values` or `errors`, but it can safely replace them with new values. ## Excluding URLs from instrumentation + -To avoid tracing certain URLs, you can specify a string of comma-separated regexes which will be matched against the full request URL. This can be passed to: - -- [`instrument_fastapi`][logfire.Logfire.instrument_fastapi] as [`excluded_urls`][logfire.Logfire.instrument_fastapi(excluded_urls)], e.g: `logfire.instrument_fastapi(app, excluded_urls='/health')` -- The environment variable `OTEL_PYTHON_FASTAPI_EXCLUDED_URLS`. -- The environment variable `OTEL_PYTHON_EXCLUDED_URLS` (which will also apply to other instrumentation). +- [Quick guide](use-cases/web-frameworks.md#excluding-urls-from-instrumentation) +- [OpenTelemetry Documentation](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/fastapi/fastapi.html#exclude-lists) ## Capturing request and response headers diff --git a/docs/integrations/flask.md b/docs/integrations/flask.md index 38744a8a..1d01245a 100644 --- a/docs/integrations/flask.md +++ b/docs/integrations/flask.md @@ -36,6 +36,12 @@ if __name__ == "__main__": The keyword arguments of `logfire.instrument_flask()` are passed to the `FlaskInstrumentor().instrument_app()` method of the OpenTelemetry Flask Instrumentation package, read more about it [here][opentelemetry-flask]. +## Excluding URLs from instrumentation + + +- [Quick guide](use-cases/web-frameworks.md#excluding-urls-from-instrumentation) +- [OpenTelemetry Documentation](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/flask/flask.html#exclude-lists) + ## Capturing request and response headers diff --git a/docs/integrations/starlette.md b/docs/integrations/starlette.md index d1c55dcb..876583cf 100644 --- a/docs/integrations/starlette.md +++ b/docs/integrations/starlette.md @@ -49,6 +49,12 @@ The keyword arguments of `logfire.instrument_starlette()` are passed to the `Sta `StarletteInstrumentor` actually wraps the ASGI middleware and adds some additional information related to the routes. +## Excluding URLs from instrumentation + + +- [Quick guide](use-cases/web-frameworks.md#excluding-urls-from-instrumentation) +- [OpenTelemetry Documentation](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/starlette/starlette.html#exclude-lists) + ## Capturing request and response headers diff --git a/docs/integrations/use-cases/web-frameworks.md b/docs/integrations/use-cases/web-frameworks.md index ff7dbaa4..ecad919b 100644 --- a/docs/integrations/use-cases/web-frameworks.md +++ b/docs/integrations/use-cases/web-frameworks.md @@ -79,3 +79,62 @@ Notice how we filtered on records that have the `http.method` attributes set. It This query is a good candidate for a Time Series chart in a dashboard: ![Requests duration per percentile as Time Series chart](../../images/integrations/use-cases/web-frameworks/logfire-screenshot-chart-percentiles.png) + + +## Excluding URLs from instrumentation + +If you want to exclude certain URLs from tracing, you can either use logfire's instrumentation methods or OpenTelemetry configuration. +You can specify said URLs using a string of comma-separated regexes which will be matched against the full request URL. + +### Using logfire + +Some methods (e.g. `logfire.instrument_fastapi()`) allow you to pass the argument `excluded_urls` as a string of comma-separated regexes. + +### Using OpenTelemetry + +You can set one of two environment variables to exclude URLs from tracing: + +- `OTEL_PYTHON_EXCLUDED_URLS`, which will also apply to all instrumentations for which excluded URLs apply). +- `OTEL_PYTHON_FASTAPI_EXCLUDED_URLS`, for example, which will only apply to FastAPI instrumentation. You can replace `FASTAPI` with the name of the framework you're using. + +!!! example + If you'd like to trace all URLs except the base `/` URL, you can use the following regex for `excluded_urls`: `^https?://[^/]+/$` + + Breaking it down: + + * `^` matches the start of the string + * `https?` matches `http` or `https` + * `://` matches `://` + * `[^/]+` matches one or more characters that are not `/` (this will be the host part of the URL) + * `/` matches `/` + * `$` matches the end of the string + + So this regex will only match routes that have no path after the host. + + This instrumentation might look like: + + ```py + from fastapi import FastAPI + + import logfire + + app = FastAPI() + + logfire.configure() + logfire.instrument_fastapi(app, excluded_urls='^https?://[^/]+/$') + + if __name__ == '__main__': + import uvicorn + + uvicorn.run(app) + ``` + + If you visit http://127.0.0.1:8000/, that matches the above regex, so no spans will be sent to Logfire. + If you visit http://127.0.0.1:8000/hello/ (or any other endpoint that's not `/`, for that matter), a trace will be started and sent to Logfire. + + !!! note + Under the hood, the `opentelemetry` library is using `re.search` (not `re.match` or `re.fullmatch`) to check for a match between the route and the `excluded_urls` regex, which is why we need to include the `^` at the start and `$` at the end of the regex. + +!!! note + Specifying excluded URLs for a given instrumentation suppresses tracing for any automatic instrumentation that applies to said framework. + It does not suppress tracing for manual instrumentation. diff --git a/docs/integrations/wsgi.md b/docs/integrations/wsgi.md index 8815bc3d..e15465c1 100644 --- a/docs/integrations/wsgi.md +++ b/docs/integrations/wsgi.md @@ -36,6 +36,11 @@ with make_server("", 8000, app) as httpd: You can read more about the OpenTelemetry WSGI middleware [here][opentelemetry-wsgi]. +## Excluding URLs from instrumentation + + +- [Quick guide](use-cases/web-frameworks.md#excluding-urls-from-instrumentation) + ## Capturing request and response headers