Add excluded_urls example for / (#487)

Co-authored-by: David Montague <[email protected]>
Co-authored-by: Alex Hall <[email protected]>

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
+<!-- note that this section is duplicated for different frameworks but with slightly different links -->
+
+- [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
 <!-- note that this section is duplicated for different frameworks but with slightly different links -->
 

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
+<!-- note that this section is duplicated for different frameworks but with slightly different links -->
+
+- [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
 <!-- note that this section is duplicated for different frameworks but with slightly different links -->
 

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
+<!-- note that this section is duplicated for different frameworks but with slightly different links -->
 
-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
 <!-- note that this section is duplicated for different frameworks but with slightly different links -->

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
+<!-- note that this section is duplicated for different frameworks but with slightly different links -->
+
+- [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
 <!-- note that this section is duplicated for different frameworks but with slightly different links -->
 

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
+<!-- note that this section is duplicated for different frameworks but with slightly different links -->
+
+- [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
 <!-- note that this section is duplicated for different frameworks but with slightly different links -->
 

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.