diff --git a/docs/integrations/asgi.md b/docs/integrations/asgi.md index a77f3ba1..13a1f311 100644 --- a/docs/integrations/asgi.md +++ b/docs/integrations/asgi.md @@ -44,6 +44,15 @@ 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) + +!!! note + `OpenTelemetryMiddleware` does accept an `excluded_urls` parameter, but does not support specifying said URLs via an environment variable, + unlike other instrumentations. + ## 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 cb0950ec..9fe55f15 100644 --- a/docs/integrations/use-cases/web-frameworks.md +++ b/docs/integrations/use-cases/web-frameworks.md @@ -81,3 +81,59 @@ You can use this query in 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) See the [DataFusion documentation](https://datafusion.apache.org/user-guide/sql/aggregate_functions_new.html#approx-percentile-cont) for more information on the `approx_percentile_cont` function. + +## 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. + +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 only prevents that specific instrumentation from creating spans/metrics, it doesn't suppress other instrumentation within the excluded endpoints.