OpenTelemetry¶

Quando sua API está em execução, você pode querer saber quanto tráfego ela recebe, quais requests são lentos e quando ocorrem erros.

Telemetria são dados sobre o comportamento da sua aplicação que ajudam a responder a essas perguntas. Os tipos comuns incluem:

• Métricas: medições que você pode resumir ao longo do tempo, como os tempos de response e o número de requests em processamento.
• Traces: registros de requests individuais e das operações realizadas para processá-los. Cada operação cronometrada é chamada de span.
• Logs: registros de eventos com marcação de tempo, como a inicialização de uma aplicação ou a falha de uma operação.

OpenTelemetry é um conjunto de padrões e ferramentas para coletar telemetria e enviá-la a um serviço de monitoramento, onde você pode explorá-la em painéis.

O FastAPI oferece suporte a OpenTelemetry por padrão para traces de requests HTTP, métricas e logs. As conexões WebSocket também fornecem traces e logs. Para visualizar esses dados, configure um serviço de monitoramento para recebê-los.

Instale o FastAPI¶

Instale o FastAPI com os extras standard, que incluem os pacotes para enviar telemetria:

$ uv add "fastapi[standard]"
---> 100%

Crie a aplicação¶

Crie um arquivo main.py:

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

Você não precisa escrever nenhum código personalizado para coletar telemetria.

FastAPI Cloud¶

Ao fazer o deploy no FastAPI Cloud com fastapi[standard], as métricas funcionam automaticamente. Não é necessário configurar mais nada.

Nos planos Pro, você pode visualizar contagens de requests, taxas de erro e tempos de response no painel de métricas.

Outros serviços de monitoramento¶

Para enviar telemetria a outro serviço de monitoramento, configure um endpoint que aceite OTLP, o protocolo do OpenTelemetry para enviar telemetria. Use o endpoint base HTTP/protobuf do serviço.

Defina estas variáveis de ambiente, substituindo a URL de exemplo pelo seu endpoint:

export FASTAPI_OTEL_AUTO_CONFIGURE=true
export OTEL_SERVICE_NAME=my-api
export OTEL_EXPORTER_OTLP_ENDPOINT=https://collector.example.com

FASTAPI_OTEL_AUTO_CONFIGURE=true habilita a configuração automática de exportadores do FastAPI. OTEL_SERVICE_NAME identifica sua aplicação no serviço de monitoramento. O endpoint é a URL base para receber dados. Os traces são enviados para /v1/traces, as métricas para /v1/metrics e os logs para /v1/logs nessa URL.

Se o serviço exigir autenticação, defina OTEL_EXPORTER_OTLP_HEADERS com os cabeçalhos especificados por ele, por exemplo, api-key=YOUR_API_KEY.

Execute a aplicação¶

Inicie a aplicação no mesmo terminal:

$ uv run fastapi run

Em outro terminal, envie um request:

$ curl http://127.0.0.1:8000/items/1
{"item_id":1}

Abra seu serviço de monitoramento e procure my-api. Após a próxima exportação, você poderá ver um trace com um span GET /items/{item_id}, junto com métricas de contagem de requests, duração de responses e requests ativos.

Personalize a telemetria¶

Configure provedores e exportadores¶

Um provedor fornece os objetos que registram traces, métricas ou logs. Sua configuração controla como esses dados são processados e exportados.

Bibliotecas de telemetria podem configurar os provedores globais do OpenTelemetry. Configure a biblioteca antes de iniciar a aplicação, e o FastAPI usará esses provedores automaticamente.

Por padrão, o FastAPI usa os provedores configurados sem adicionar exportadores. Quando a configuração automática está habilitada e um endpoint OTLP é definido no ambiente, o FastAPI adiciona um exportador para esse destino a cada provedor habilitado. Os exportadores existentes continuam enviando dados aos seus destinos.

Se outra biblioteca já configura a exportação para o mesmo destino, deixe FASTAPI_OTEL_AUTO_CONFIGURE sem definir ou defina como false para evitar telemetria duplicada.

Você também pode passar um provedor diretamente no dicionário telemetry. Por exemplo, este provedor usa o exportador de console do OpenTelemetry para exibir spans de requests no seu terminal:

from fastapi import FastAPI
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter

tracer_provider = TracerProvider()
tracer_provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))

app = FastAPI(telemetry={"tracer_provider": tracer_provider})


@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

O exportador envia os spans ao destino. BatchSpanProcessor agrupa spans e os envia em segundo plano. Substitua o exportador de console por um fornecido pela sua biblioteca de monitoramento para usar o destino dela. Consulte o tutorial de instrumentação Python do OpenTelemetry para mais opções de configuração.

Use meter_provider ou logger_provider no mesmo dicionário para fornecer um provedor de métricas ou logs. A aplicação ou biblioteca que cria um provedor gerencia seu encerramento. O FastAPI gerencia os componentes de exportação que adiciona.

Rastreie operações de requests¶

Por padrão, os traces de requests incluem spans para resolver dependências, executar sua função de operação de rota, serializar a response e executar cada tarefa em BackgroundTasks do FastAPI. Esses spans usam o mesmo provedor e os mesmos exportadores.

Os spans de tarefas em segundo plano continuam fazendo parte do trace do request. Eles são executados após o término do span da response HTTP, portanto não aumentam o tempo de response medido.

Para registrar apenas o span do request HTTP, defina operation_spans como False:

from fastapi import FastAPI

app = FastAPI(telemetry={"operation_spans": False})


@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

Rastreie conexões WebSocket¶

Cada conexão WebSocket tem um span como WS /ws/{room}, que abrange o manipulador e a limpeza das dependências. Ele usa os mesmos provedores e configurações, incluindo operation_spans para a resolução de dependências e a execução do endpoint.

As métricas de requests HTTP abrangem apenas requests HTTP. Desconexões normais de WebSocket com os códigos 1000 ou 1001 não produzem logs de erro.

Inspecione erros¶

O FastAPI registra exceções não tratadas como logs do OpenTelemetry, vinculados ao trace do request ou da conexão. Os logs de erro são registrados mesmo quando o trace não é selecionado na amostragem.

Os logs de exceções incluem o tipo, a mensagem e o stack trace da exceção. Mensagens e stack traces podem conter informações sensíveis. Use os processadores de logs do seu provedor para filtrar ou ocultar essas informações, ou defina logs como False para desabilitar esses logs.

O FastAPI também registra falhas de validação de requests como logs de aviso com a rota e a contagem de erros. Esses logs não incluem os dados de entrada inválidos.

Escolha o que registrar¶

O dicionário telemetry também aceita estas configurações:

Por exemplo, para coletar métricas excluindo verificações de integridade:

from fastapi import FastAPI

app = FastAPI(
    telemetry={
        "tracing": False,
        "exclude": lambda scope: scope["path"] == "/health",
    }
)

Um valor explícito de auto_configure no dicionário telemetry tem precedência sobre FASTAPI_OTEL_AUTO_CONFIGURE. Use telemetry={"auto_configure": True} para habilitar a configuração automática no código, ou telemetry={"auto_configure": False} para desabilitá-la em uma aplicação mesmo quando a variável de ambiente a habilita.