Logs de aplicação

O Logs do Toqan Router armazena os registros de log do OpenTelemetry que uma aplicação exporta, junto com os Traces 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 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

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:

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"

$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 para implantações auto-hospedadas.

Configure o SDK de logging

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

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"}
)

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.

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. 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:

{
  "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 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 para filtragem, agregação e facets, e a OQL para consultas em pipeline.
A Telemetry API 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.

Visão geral

Instrumente seu app

Explorar

Monitorar

Exportar

Revisar

Privacidade e segurança de dados

Integrações com frameworks

Pré-requisitos

Enviar logs

Defina o endpoint e as credenciais

Configure o SDK de logging

Correlacione logs com traces

Registros de log

Frameworks

Consultar logs

Limites

​Pré-requisitos

​Enviar logs

Defina o endpoint e as credenciais

Configure o SDK de logging

Correlacione logs com traces

​Registros de log

​Frameworks

​Consultar logs

​Limites

Pré-requisitos

Enviar logs

Registros de log

Frameworks

Consultar logs

Limites