FastAPI exception handlers: properly handled exceptions logged as errors in Logfire

[renaudcepre]

Question

FastAPI exception handlers: properly handled domain exceptions logged as errors in Logfire

Summary

When using Logfire's instrument_fastapi(), exceptions that are properly handled by FastAPI exception handlers are still logged as errors in Logfire, even though they result in valid HTTP responses (404, 403, etc.). This pollutes error logs with normal business logic cases.

Expected Behavior

Exceptions that are handled by FastAPI exception handlers and converted to proper HTTP responses (4xx status codes) should NOT be logged as errors in Logfire. They should either not be logged as exceptions at all

Actual Behavior

All exceptions are logged as errors in Logfire, regardless of whether they're handled by exception handlers.

Code Example

Exception Handler Setup:

from fastapi import FastAPI
from fastapi.responses import JSONResponse
from generic_rag.domain.exceptions.base import DomainError

@app.exception_handler(DomainError)
async def domain_error_handler(request: Request, exc: DomainError) -> Response:
    return JSONResponse(status_code=404, content={"detail": str(exc)})

# Logfire instrumentation
logfire.instrument_fastapi(app, capture_headers=True)

Route that raises handled exception:

@router.get("/users/{user_id}")
def get_user(user_id: UUID) -> User:
    # This raises UserNotFoundError which inherits from DomainError
    return domain.get_user_for_company(user_id, api_user)

Result in Logfire

{
  "is_exception": true,
  "exception_type": "generic_rag.domain.exceptions.users.UserNotFoundError", 
  "otel_status_code": "ERROR",
  "http_response_status_code": 404
}

The HTTP response is correctly 404, but Logfire still logs it as an error.

Workaround

Currently, the only workaround is to wrap every route in try/catch, which contradicts the use of error handler:

@router.get("/users/{user_id}")  
def get_user(user_id: UUID) -> User:
    try:
        return domain.get_user_for_company(user_id, api_user)
    except DomainError as exc:
        # Handle manually to avoid Logfire logging as error
        return JSONResponse(status_code=404, content={"detail": str(exc)})

With this approach:

{
  "is_exception": false,
  "otel_status_code": "UNSET", 
  "http_response_status_code": 404
}

Questions

Am I missing something obvious here? I've searched through the documentation and tried different approaches, but couldn't find a clean solution that preserves the benefits of FastAPI's exception handler pattern while avoiding the error log pollution.

Environment

>>> import logfire; print(logfire.logfire_info())
logfire="4.3.3"
python="3.11.9 (main, Aug 14 2024, 05:07:28) [Clang 18.1.8 ]"
[related_packages]
requests="2.32.4"
pydantic="2.11.7"
fastapi="0.104.1"
openai="1.97.2"
protobuf="5.29.5"
rich="14.0.0"
executing="2.2.0"
opentelemetry-api="1.36.0"
opentelemetry-exporter-otlp="1.36.0"
opentelemetry-exporter-otlp-proto-common="1.36.0"
opentelemetry-exporter-otlp-proto-grpc="1.36.0"
opentelemetry-exporter-otlp-proto-http="1.36.0"
opentelemetry-instrumentation="0.57b0"
opentelemetry-instrumentation-asgi="0.57b0"
opentelemetry-instrumentation-celery="0.57b0"
opentelemetry-instrumentation-fastapi="0.57b0"
opentelemetry-instrumentation-llamaindex="0.45.6"
opentelemetry-instrumentation-sqlalchemy="0.57b0"
opentelemetry-proto="1.36.0"
opentelemetry-sdk="1.36.0"
opentelemetry-semantic-conventions="0.57b0"
opentelemetry-semantic-conventions-ai="0.4.12"
opentelemetry-util-http="0.57b0"

Sorry for the images that don't exactly match the snippets.

[renaudcepre]

Update: After reviewing Logfire's test suite

I found this behavior is intentional - it's explicitly tested in test_fastapi_handled_exception with the comment:

  # FastAPI automatically handles RequestValidationError and returns a 422 response.
  # Our instrumentation still captures the exception as it happens in the endpoint.

While I understand the "capture everything" philosophy, this creates production problems:

• Misleading dashboards: Normal business flow appears as errors
• Contradicts FastAPI patterns: Exception handlers become pointless

Perhaps it would be possible to add a configuration option instead of changing defaults ?

logfire.instrument_fastapi(app, record_handled_exceptions=False)

The ability to distinguish handled exceptions (business flow) from unhandled exceptions (real errors) is crucial for reliable monitoring.

[alexmojaki]

The exception is recorded so that you can see a traceback, because it won't always be obvious where the exception came from and you may want to know. That's the history behind that comment, it was requested by a user long ago.

The exception is not logged as an error. Exceptions and errors are different things. The level of the span, as seen in the screenshot, is still 'info'. I recognise that some parts of the UI still show as red, and we should address that, cc @summerscope @dmontagu @petyosi. But the intended user workflow is to query level >= 'error' when you want to find errors. For example, the standard exceptions dashboard does this by default.

#1355 will allow avoiding recording the exception at all if you really want.

[renaudcepre]

Thank you for the detailed explanation !

I find it quite surprising behavior to report the error and its traceback. From a
technical standpoint, when I have an exception that I catch to handle it (even if I let the FastAPI error handler do it for me), having an exception with a traceback doesn't make sense in this case for me.

When an exception is handled by a registered exception handler, it's part of the normal application flow - it's a controlled way to return specific HTTP responses based on business logic. Recording these exceptions creates
noise in the observability data and makes it harder to identify genuine errors that require attention.

For what it's worth, I implemented a small solution on my side for fun and testing: #1363
(Happy to close this if it's not helpful - just sharing)

It adds automatic detection of FastAPI exception handlers and only records truly unhandled exceptions when record_handled_exceptions=False. If this approach doesn't align with logfire's philosophy, that's totally fine -
but this is exactly the behavior I'm looking for, just as a reference.

Thanks :)

[alexmojaki]

#1355 is now merged making it possible to avoid recording exceptions in general: https://logfire.pydantic.dev/docs/reference/api/types/#logfire.types.ExceptionCallback

Something to check in your PR: is HTTPException(status_code=500) also not recorded with this flag enabled?