> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Logs de aplicação

> Envie registros de log do OpenTelemetry para o Toqan Router e pesquise-os no Logs Explorer, filtrando por ID do trace.

O Logs do **Toqan Router** armazena os registros de log do OpenTelemetry que uma aplicação exporta, junto com os [Traces](/docs/pt-BR/ai-studio/observability/traces.md) que o **Toqan Router** já coleta. Um trace mostra as etapas de uma solicitação; um registro de log contém uma mensagem com carimbo de data/hora vinda do código da aplicação. Registros que contêm o `trace_id` e o `span_id` ativos podem ser filtrados por **Trace ID** no **Logs Explorer**.

Os logs chegam pelo mesmo endpoint OTLP que os traces, como um sinal separado. O endpoint aceita o sinal de logs do OTLP em `/v2/otel/v1/logs`. Abra **Logs** na barra lateral do [AI Studio](https://router.toqan.ai/eu) para pesquisar os registros armazenados.

## Pré-requisitos

* Um workspace do **Toqan Router** e uma chave de API. Crie uma em **Settings > Organization > API Keys** e exporte-a como `TOQAN_API_KEY`.
* O SDK de logging do OpenTelemetry e o exportador OTLP HTTP para a linguagem utilizada.

## Enviar logs

### 1. Defina o endpoint e as credenciais

Os exportadores leem o endpoint e os cabeçalhos do ambiente. Defina ambos, além dos atributos de recurso que identificam o serviço:

```bash macOS / Linux theme={"theme":{"light":"github-light","dark":"github-dark"}}
export OTEL_EXPORTER_OTLP_ENDPOINT="https://router.toqan.ai/eu/v2/otel"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer $TOQAN_API_KEY"
export OTEL_RESOURCE_ATTRIBUTES="service.name=my-app,service.version=1.0.0"
```

```powershell Windows theme={"theme":{"light":"github-light","dark":"github-dark"}}
$env:OTEL_EXPORTER_OTLP_ENDPOINT = "https://router.toqan.ai/eu/v2/otel"
$env:OTEL_EXPORTER_OTLP_HEADERS = "Authorization=Bearer $env:TOQAN_API_KEY"
$env:OTEL_RESOURCE_ATTRIBUTES = "service.name=my-app,service.version=1.0.0"
```

O SDK de logging do OpenTelemetry acrescenta `/v1/logs` ao endpoint base, de modo que os registros chegam a `https://router.toqan.ai/eu/v2/otel/v1/logs`. Consulte [Base URLs](/docs/pt-BR/reference/base-urls.md) para implantações auto-hospedadas.

### 2. Configure o SDK de logging

Crie um logger provider, anexe o exportador OTLP e conecte o logger padrão da aplicação a ele:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import logging

from opentelemetry._logs import set_logger_provider
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor

provider = LoggerProvider()
provider.add_log_record_processor(BatchLogRecordProcessor(OTLPLogExporter()))
set_logger_provider(provider)

logging.basicConfig(level=logging.INFO)

logging.getLogger().addHandler(
    LoggingHandler(level=logging.INFO, logger_provider=provider)
)

logging.getLogger("checkout-service").info(
    "Order processed", extra={"order.id": "A-1024"}
)
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { logs, SeverityNumber } from '@opentelemetry/api-logs';
import { LoggerProvider, BatchLogRecordProcessor } from '@opentelemetry/sdk-logs';
import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http';

const loggerProvider = new LoggerProvider();
loggerProvider.addLogRecordProcessor(
  new BatchLogRecordProcessor(new OTLPLogExporter()),
);
logs.setGlobalLoggerProvider(loggerProvider);

const logger = logs.getLogger('checkout-service');
logger.emit({
  severityNumber: SeverityNumber.INFO,
  severityText: 'INFO',
  body: 'Order processed',
  attributes: { 'order.id': 'A-1024' },
});
```

Instale primeiro os pacotes do exportador e do SDK: `pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http` para Python ou `npm install @opentelemetry/api-logs @opentelemetry/sdk-logs @opentelemetry/exporter-logs-otlp-http` para Node.js.

### 3. Correlacione logs com traces

Quando um registro é emitido enquanto um span está ativo, o exportador anexa o `trace_id` e o `span_id` desse span. Filtre o **Logs Explorer** por **Trace ID** para obter todos os registros de uma solicitação, ou leia-os pela API com [List logs for a trace](/docs/pt-BR/reference/logs/list-logs-for-a-trace.md). Registros emitidos fora de um span não têm contexto de trace e só podem ser pesquisados pelos outros campos.

## Registros de log

A página **Logs** tem duas abas. **Explorer** mostra uma linha por registro. **Patterns** agrupa os registros que compartilham um modelo de mensagem.

No **Explorer**, a barra de ferramentas contém **Filter**, o intervalo de tempo (**7 days** por padrão), o seletor de visualizações salvas (**All Rows**), **Fields**, **Copy for MCP**, **Reload** e **Live**. O painel à esquerda lista as **Facets** do conjunto de resultados atual, e **Search facets** encontra uma pelo nome.

**Fields** abre o painel de colunas. Seu cabeçalho conta as colunas visíveis em relação às disponíveis, como `5/12`, e o painel alterna entre **All columns** e **Selected**.

| Coluna | Campo do registro | Observações |
| - | - | - |
| **Timestamp** | `timestamp` | Quando o evento ocorreu |
| **Severity** | `severity_text` e `severity_number` | Usa o texto, em minúsculas, quando definido; caso contrário, é derivado da severidade numérica |
| **Service** | `service_name` | Promovido a partir do atributo de recurso `service.name` |
| **Body** | `body` | A mensagem, ou o payload JSON quando o corpo é estruturado |
| **Duration** | `observed_timestamp` menos `timestamp` | O tempo entre o evento e sua ingestão |
| **Event** | `event_name` | O nome do evento, quando definido |
| **Scope** | `scope_name` | O escopo de instrumentação que emitiu o registro |
| **Environment** | `deployment_environment` | Promovido a partir de `deployment.environment` ou `deployment.environment.name` |
| **Host** | `host_name` | Promovido a partir de `host.name` |
| **Project** | `project_id` | O projeto que recebeu a exportação |
| **Trace ID** | `trace_id` | O trace ativo, quando havia um |
| **Span ID** | `span_id` | O span ativo, quando havia um |

Os atributos permanecem agrupados por origem e podem ser pesquisados no painel de campos e no menu de filtros:

* **Atributos de log**: atributos definidos no registro individual, por exemplo `order.id`.
* **Atributos de recurso**: atributos definidos para todo o processo, por exemplo `service.name` ou `deployment.environment`.
* **Atributos de escopo**: atributos definidos pela biblioteca de instrumentação.

Uma exportação OTLP tem este formato:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "resourceLogs": [
    {
      "resource": {
        "attributes": [
          { "key": "service.name", "value": { "stringValue": "checkout-service" } }
        ]
      },
      "scopeLogs": [
        {
          "scope": { "name": "checkout-service" },
          "logRecords": [
            {
              "timeUnixNano": "1759600000000000000",
              "severityNumber": 9,
              "severityText": "INFO",
              "body": { "stringValue": "Order processed" },
              "attributes": [
                { "key": "order.id", "value": { "stringValue": "A-1024" } }
              ],
              "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
              "spanId": "00f067aa0ba902b7"
            }
          ]
        }
      ]
    }
  ]
}
```

## Frameworks

Qualquer SDK de logging do OpenTelemetry que exporte OTLP por HTTP pode enviar dados para o **Toqan Router**: o sinal é independente da instrumentação de tracing, portanto os logs de um framework que só instrumenta traces também chegam depois que o SDK de logging é configurado no mesmo processo.

Os [guias de frameworks](/docs/pt-BR/ai-studio/integrations/frameworks/overview.md) configuram o sinal de traces. Adicione a configuração do SDK de logging acima ao mesmo processo para exportar logs junto com esses traces; o contexto do span ativo mantém ambos correlacionados.

## Consultar logs

O **Logs Explorer** oferece busca em texto livre, filtros sobre campos nativos e dinâmicos e detecção de padrões sobre uma amostra limitada. As combinações de filtros salvas são visualizações reutilizáveis.

Os mesmos dados estão disponíveis de forma programática:

* A [Logs API](/docs/pt-BR/reference/logs/search-logs.md) para filtragem, agregação e facets, e a [OQL](/docs/pt-BR/ai-studio/observability/oql.md) para consultas em pipeline.
* A [Telemetry API](/docs/pt-BR/ai-studio/observability/telemetry-api.md) para consultas entre sinais.
* O servidor **Toqan Router MCP** expõe `search_logs`, `get_log` e `find_log_patterns` para assistentes de programação.

## Limites

| Limite | Valor | Comportamento quando excedido |
| - | - | - |
| Registros por solicitação de exportação | 10.000 | A solicitação é rejeitada com `413` |
| Atributos por lista de atributos | 128 | O excedente é descartado |
| Comprimento da chave de atributo | Mais de 512 bytes | A chave é descartada |
| Tamanho do corpo da solicitação | 64 MB | A solicitação é rejeitada com `413` após a descompressão |
| Ingestão no plano Free | Cota do plano | A solicitação é rejeitada com `429` e um cabeçalho `Retry-After` |

Uma exportação repetida é deduplicada com base nas mesmas posições do lote, portanto um lote reenviado não cria duplicatas. Linhas idênticas dentro de uma mesma exportação permanecem distintas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.