Observabilidade¶

A partir da versão 3.5.0, o BotCity Runner oferece recursos de observabilidade para monitorar, solucionar problemas e obter insights sobre o desempenho das automações.

Visão Geral¶

O BotCity Runner oferece observabilidade abrangente por meio de:

Logs Estruturados — Formato TEXT ou JSON com metadados contextuais detalhados
Integração com OpenTelemetry — Exportação de logs para qualquer backend compatível com OTLP
Propagação de Contexto via MDC — Correlação consistente entre as entradas de log

Referência de Configuração¶

Variáveis de Ambiente¶

Variável	Padrão	Descrição
`BOTCITY_RUNNER_LOG_DIR`	`./logs`	Diretório dos arquivos de log
`BOTCITY_RUNNER_LOG_FORMAT`	`TEXT`	Formato do log: `TEXT` ou `JSON`
`BOTCITY_RUNNER_LOG_LEVEL`	`INFO`	Nível de log do pacote `dev.botcity.runner`
`BOTCITY_RUNNER_LOG_CONSOLE`	`false`	Habilita a saída no console
`BOTCITY_RUNNER_OTEL_ENABLED`	`false`	Habilita a exportação via OpenTelemetry

Variáveis do OpenTelemetry¶

Quando BOTCITY_RUNNER_OTEL_ENABLED=true, o Runner respeita as variáveis de ambiente padrão do OTEL:

Variável	Padrão	Descrição
`OTEL_EXPORTER_OTLP_ENDPOINT`	`http://localhost:4317`	URL do endpoint OTLP
`OTEL_EXPORTER_OTLP_HEADERS`	—	Cabeçalhos de autenticação (`key=value,key2=value2`)
`OTEL_EXPORTER_OTLP_PROTOCOL`	`grpc`	Protocolo: `grpc` ou `http/protobuf`
`OTEL_EXPORTER_OTLP_COMPRESSION`	—	Compressão: `gzip` ou `none`
`OTEL_EXPORTER_OTLP_TIMEOUT`	—	Tempo limite da requisição em milissegundos
`OTEL_SERVICE_NAME`	`botcity-runner`	Nome do serviço para identificação
`OTEL_RESOURCE_ATTRIBUTES`	—	Atributos adicionais (`key=value,key2=value2`)

Campos de Contexto do Log¶

Toda entrada de log inclui metadados contextuais via MDC (Mapped Diagnostic Context):

Campo	Descrição
`organization`	Identificador da organização
`runnerLabel`	Label da instância do Runner
`runnerVersion`	Versão do software do Runner
`automationLabel`	Label da automação
`technology`	Tecnologia do bot (Python, Java, etc.)
`botId`	Label/Identificador do Bot
`botVersion`	Versão do bot
`taskId`	Identificador da tarefa atual

Esses campos permitem filtragem e correlação em sistemas distribuídos.

Formatos de Log¶

Formato TEXT (Padrão)¶

Formato legível por humanos, adequado para desenvolvimento local e gestão tradicional de logs:

2026-04-21 13:00:00.123 INFO  [org=acme] [runner=prod-01] [runnerVersion=3.5.0] [automation=invoice-bot] [technology=python] [botId=inv-001] [botVersion=1.2.0] [taskId=12345] Starting task execution

Formato JSON¶

Formato JSON estruturado, compatível com plataformas de agregação de logs (ELK, Splunk, Datadog, etc.):

{
  "@timestamp": "2026-04-21T13:00:00.123Z",
  "level": "INFO",
  "message": "Starting task execution",
  "organization": "acme",
  "runnerLabel": "prod-01",
  "runnerVersion": "3.5.0",
  "automationLabel": "invoice-bot",
  "technology": "python",
  "botId": "inv-001",
  "botVersion": "1.2.0",
  "taskId": "12345",
  "application": "botcity-runner",
  "service.name": "botcity-runner"
}

Habilite com:

export BOTCITY_RUNNER_LOG_FORMAT=JSON

Integração com Plataformas de Observabilidade¶

O BotCity Runner suporta integração direta com plataformas de observabilidade via OpenTelemetry. Nenhum coletor intermediário é necessário — o Runner envia os logs diretamente para esses serviços.

Dynatrace¶

O Dynatrace oferece observabilidade full-stack com análise impulsionada por IA.

export BOTCITY_RUNNER_OTEL_ENABLED=true
export OTEL_EXPORTER_OTLP_ENDPOINT=https://{environment-id}.live.dynatrace.com/api/v2/otlp
export OTEL_EXPORTER_OTLP_HEADERS=Authorization=Api-Token dt0c01.xxxxxxxxxxxx
export OTEL_SERVICE_NAME=botcity-runner

Passos de configuração:

No Dynatrace, acesse Settings → Integration → API tokens
Crie um token com o escopo logs.ingest
Substitua {environment-id} pelo ID do seu ambiente Dynatrace
Substitua dt0c01.xxxxxxxxxxxx pelo seu token de API

Visualizando os logs:

Navegue até Observe and explore → Logs
Filtre por service.name = "botcity-runner"
Use DQL para consultar: fetch logs | filter service.name == "botcity-runner"

New Relic¶

O New Relic oferece observabilidade unificada com consultas poderosas via NRQL.

export BOTCITY_RUNNER_OTEL_ENABLED=true
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.nr-data.net:4318
export OTEL_EXPORTER_OTLP_HEADERS=api-key=NRAK-xxxxxxxxxxxxxxxxxxxx
export OTEL_SERVICE_NAME=botcity-runner

Passos de configuração:

No New Relic, acesse API keys (menu do usuário → API keys)
Crie ou copie sua License key (começa com NRAK-)
Para o datacenter da UE, use https://otlp.eu01.nr-data.net:4318

Visualizando os logs:

Navegue até Logs
Filtre por service.name = "botcity-runner"
Use NRQL: SELECT * FROM Log WHERE service.name = 'botcity-runner'

Consultas NRQL úteis:

-- Taxa de erro por automação
SELECT count(*) FROM Log 
WHERE service.name = 'botcity-runner' AND level = 'ERROR'
FACET automationLabel TIMESERIES

-- Linha do tempo da execução da tarefa
SELECT * FROM Log 
WHERE service.name = 'botcity-runner' AND taskId = '12345'
ORDER BY timestamp

Datadog¶

O Datadog oferece monitoramento abrangente com análise de logs e correlação com APM.

export BOTCITY_RUNNER_OTEL_ENABLED=true
export OTEL_EXPORTER_OTLP_ENDPOINT=https://http-intake.logs.datadoghq.com:443
export OTEL_EXPORTER_OTLP_HEADERS=DD-API-KEY=xxxxxxxxxxxxxxxxxxxx
export OTEL_SERVICE_NAME=botcity-runner

Passos de configuração:

No Datadog, acesse Organization Settings → API Keys
Crie ou copie uma chave de API
Para o site da UE, use https://http-intake.logs.datadoghq.eu:443

Visualizando os logs:

Navegue até Logs → Search
Filtre por service:botcity-runner
Crie facets para @taskId, @botId, @automationLabel para filtragem eficiente

Consultas úteis:

service:botcity-runner status:error
service:botcity-runner @taskId:12345
service:botcity-runner @automationLabel:invoice-bot

Grafana Cloud¶

O Grafana Cloud oferece observabilidade baseada em código aberto, com Loki para logs.

export BOTCITY_RUNNER_OTEL_ENABLED=true
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp-gateway-prod-us-central-0.grafana.net/otlp
export OTEL_EXPORTER_OTLP_HEADERS=Authorization=Basic <base64(instanceId:apiKey)>
export OTEL_SERVICE_NAME=botcity-runner

Passos de configuração:

No Grafana Cloud, acesse sua stack → Connections → OpenTelemetry
Anote a URL do endpoint OTLP (varia por região)
Crie um token de API com o escopo logs:write
Codifique instanceId:apiKey em Base64 para o cabeçalho Authorization:
```
echo -n "123456:glc_xxxxxxxxxxxx" | base64
```

Visualizando os logs:

Navegue até Explore → Selecione a fonte de dados Loki
Use LogQL: {service_name="botcity-runner"}

Consultas LogQL úteis:

# Filtrar por tarefa
{service_name="botcity-runner"} | json | taskId="12345"

# Logs de erro com contexto
{service_name="botcity-runner"} | json | level="ERROR"

# Buscar por automação
{service_name="botcity-runner"} | json | automationLabel="invoice-bot"

Utilizando um OpenTelemetry Collector¶

Para cenários avançados (buffering, transformação, roteamento para múltiplos destinos), implante um OpenTelemetry Collector como intermediário.

Quando Utilizar um Collector¶

Roteamento para múltiplos destinos — Envie logs para diversos backends simultaneamente
Transformação de dados — Enriqueça, filtre ou redija os dados de log
Buffering — Lide com interrupções de rede de forma resiliente
Gerenciamento de credenciais — Mantenha as chaves de API no collector, e não no Runner

Configuração Básica do Collector¶

# otel-collector-config.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    timeout: 1s
    send_batch_size: 1024

exporters:
  # Exemplo: Datadog
  datadog:
    api:
      key: ${DD_API_KEY}
      site: datadoghq.com

  # Exemplo: New Relic
  otlp/newrelic:
    endpoint: https://otlp.nr-data.net:4317
    headers:
      api-key: ${NEW_RELIC_LICENSE_KEY}

  # Exemplo: Dynatrace
  otlphttp/dynatrace:
    endpoint: https://{environment-id}.live.dynatrace.com/api/v2/otlp
    headers:
      Authorization: "Api-Token ${DT_API_TOKEN}"

service:
  pipelines:
    logs:
      receivers: [ otlp ]
      processors: [ batch ]
      exporters: [ datadog, otlp/newrelic, otlphttp/dynatrace ]

Configure o Runner para enviar os logs ao collector:

export BOTCITY_RUNNER_OTEL_ENABLED=true
export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector-host:4317
export OTEL_SERVICE_NAME=botcity-runner

Boas Práticas¶

1. Use Nomenclatura de Serviço Consistente¶

Defina OTEL_SERVICE_NAME de forma consistente em todas as instâncias do Runner:

export OTEL_SERVICE_NAME=botcity-runner

Adicione contexto de ambiente via atributos de recurso:

export OTEL_RESOURCE_ATTRIBUTES="deployment.environment=production,service.version=3.5.0"

2. Habilite o Formato JSON para Agregação de Logs¶

Ao utilizar plataformas de agregação de logs sem OTEL, habilite o formato JSON:

export BOTCITY_RUNNER_LOG_FORMAT=JSON

Isso permite a análise estruturada e a extração de campos.

3. Estratégia de Retenção de Logs¶

Considere suas necessidades de retenção:

Arquivos locais — 7 dias, limite de 1GB (padrão)
Backend OTEL — Configure de acordo com os requisitos de conformidade

Solução de Problemas¶

Logs Não Aparecem no Backend¶

Verifique se o OTEL está habilitado:

echo $BOTCITY_RUNNER_OTEL_ENABLED  # Deve retornar "true"

Verifique a conectividade com o endpoint:
```
curl -v $OTEL_EXPORTER_OTLP_ENDPOINT
```
Verifique se os cabeçalhos de autenticação estão corretos
Verifique os logs de inicialização do Runner em busca de erros de inicialização do OTEL

Campos de Contexto Ausentes¶

Certifique-se de que o Runner esteja configurando o contexto MDC corretamente. Verifique se:

A execução da tarefa está passando pelo fluxo de execução padrão
Nenhuma exceção está ocorrendo antes que o contexto seja definido

Alta Latência ou Logs Descartados¶

Se estiver utilizando a integração direta:

Considere implantar um collector para buffering
Verifique a latência de rede até o backend
Verifique se os limites de taxa do backend não estão sendo atingidos

Comportamento de Retentativa e Resiliência¶

O SDK do OpenTelemetry inclui lógica de retentativa integrada para falhas transitórias ao exportar logs:

Comportamento Padrão¶

Configuração	Valor Padrão	Descrição
Retentativa habilitada	Sim	Retentativa automática em caso de falhas transitórias
Backoff inicial	1 segundo	Tempo de espera antes da primeira retentativa
Backoff máximo	5 segundos	Tempo máximo de espera entre retentativas
Multiplicador de backoff	1.5	Fator de backoff exponencial
Máximo de tentativas	5	Total de retentativas antes de descartar
Timeout de exportação	10 segundos	Timeout por requisição (configurável via `OTEL_EXPORTER_OTLP_TIMEOUT`)

O Que Acontece Durante Indisponibilidades¶

Indisponibilidades curtas (< 30 segundos) — Os logs são armazenados em buffer e reenviados automaticamente
Indisponibilidades prolongadas — Após o máximo de retentativas, os logs são descartados (gravados localmente se o file appender estiver habilitado)
Encerramento gracioso — Ao encerrar a JVM, o SDK descarrega os logs pendentes antes de terminar

Ajustes para o Seu Ambiente¶

Para redes de alta latência ou conexões instáveis:

# Aumentar o timeout da requisição (milissegundos)
export OTEL_EXPORTER_OTLP_TIMEOUT=30000

# Habilitar compressão para reduzir o consumo de banda
export OTEL_EXPORTER_OTLP_COMPRESSION=gzip

Para ambientes de produção com requisitos rigorosos de confiabilidade, considere implantar um OpenTelemetry Collector como buffer local.

Observabilidade¶

Visão Geral¶

Referência de Configuração¶

Variáveis de Ambiente¶

Variáveis do OpenTelemetry¶

Campos de Contexto do Log¶

Formatos de Log¶

Formato TEXT (Padrão)¶

Formato JSON¶

Integração com Plataformas de Observabilidade¶

Dynatrace¶

New Relic¶

Datadog¶

Grafana Cloud¶

Utilizando um OpenTelemetry Collector¶

Quando Utilizar um Collector¶

Configuração Básica do Collector¶

Boas Práticas¶

1. Use Nomenclatura de Serviço Consistente¶

2. Habilite o Formato JSON para Agregação de Logs¶

3. Estratégia de Retenção de Logs¶

Solução de Problemas¶

Logs Não Aparecem no Backend¶

Campos de Contexto Ausentes¶

Alta Latência ou Logs Descartados¶

Comportamento de Retentativa e Resiliência¶

Comportamento Padrão¶

O Que Acontece Durante Indisponibilidades¶

Ajustes para o Seu Ambiente¶

Referências¶