From 39a68b9784ae8f3d187abe0ba63a82e4b60cafdb Mon Sep 17 00:00:00 2001 From: "pr-submit[bot]" <314742883+pr-submit[bot]@users.noreply.github.com> Date: Fri, 2 Oct 2026 13:13:42 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=8C=90=20Update=20translations=20for=20pt?= =?UTF-8?q?=20(add-missing)=20(#16431)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: pr-submit[bot] Co-authored-by: Yurii Motov --- docs/pt/docs/advanced/opentelemetry.md | 161 +++++++++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 docs/pt/docs/advanced/opentelemetry.md diff --git a/docs/pt/docs/advanced/opentelemetry.md b/docs/pt/docs/advanced/opentelemetry.md new file mode 100644 index 0000000000..53a24c02a2 --- /dev/null +++ b/docs/pt/docs/advanced/opentelemetry.md @@ -0,0 +1,161 @@ +# OpenTelemetry { #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**](https://opentelemetry.io/) é 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 { #install-fastapi } + +Instale o FastAPI com os extras `standard`, que incluem os pacotes para enviar telemetria: + +
+ +```console +$ uv add "fastapi[standard]" +---> 100% +``` + +
+ +## Crie a aplicação { #create-the-app } + +Crie um arquivo `main.py`: + +{* ../../docs_src/opentelemetry/tutorial001_py310.py *} + +Observe que tudo funciona por padrão, sem precisar escrever código personalizado para a telemetria funcionar. + +## FastAPI Cloud { #fastapi-cloud } + +Ao fazer o deploy no [FastAPI Cloud](https://fastapicloud.com) 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](https://fastapicloud.com/docs/monitoring-and-performance/metrics/). + +Painel de métricas do FastAPI Cloud Pro com dados de exemplo + +## Outros serviços de monitoramento { #other-monitoring-services } + +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: + +```bash +export OTEL_SERVICE_NAME=my-api +export OTEL_EXPORTER_OTLP_ENDPOINT=https://collector.example.com +``` + +`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 { #run-the-app } + +Inicie a aplicação no mesmo terminal: + +
+ +```console +$ uv run fastapi run +``` + +
+ +Em outro terminal, envie um request: + +```console +$ 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 { #customize-telemetry } + +### Configure provedores e exportadores { #configure-providers-and-exporters } + +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. + +Quando 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. + +Configure cada destino uma única vez. Se outra biblioteca já cuida do destino definido no ambiente, desabilite a exportação dela para esse destino ou desative a configuração automática do FastAPI: + +```python +app = FastAPI(telemetry={"auto_configure": False}) +``` + +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: + +{* ../../docs_src/opentelemetry/tutorial002_py310.py hl[2:8] *} + +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](https://opentelemetry.io/docs/languages/python/instrumentation/) 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. + +/// warning | Atenção + +O OpenTelemetry usa provedores globais por padrão. A configuração independente de telemetria para [subaplicações montadas](sub-applications.md) não é garantida. + +/// + +### Rastreie operações de requests { #trace-request-operations } + +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`: + +{* ../../docs_src/opentelemetry/tutorial003_py310.py hl[3] *} + + +### Rastreie conexões WebSocket { #trace-websocket-connections } + +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 { #inspect-errors } + +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 { #choose-what-to-record } + +O dicionário `telemetry` também aceita estas configurações: + +| Configuração | Finalidade | Padrão | +| --- | --- | --- | +| `tracing` | Registrar spans de requests HTTP e conexões WebSocket | `True` | +| `metrics` | Registrar métricas de requests HTTP | `True` | +| `logs` | Registrar falhas de validação e exceções não tratadas | `True` | +| `operation_spans` | Adicionar spans para operações de requests | `True` | +| `exclude` | Ignorar requests quando uma função que recebe o escopo ASGI retorna `True` | `None` | +| `auto_configure` | Adicionar exportadores para endpoints definidos em variáveis de ambiente | `True` | + +Por exemplo, para coletar métricas excluindo verificações de integridade: + +```python +from fastapi import FastAPI + +app = FastAPI( + telemetry={ + "tracing": False, + "exclude": lambda scope: scope["path"] == "/health", + } +) +``` + +Defina `auto_configure` como `False` quando sua aplicação cuidar da configuração dos provedores por conta própria, por exemplo, dentro da função lifespan.