Observabilidad¶

A partir de la versión 3.5.0, BotCity Runner ofrece funcionalidades de observabilidad para monitorear, solucionar problemas y obtener información sobre el rendimiento de las automatizaciones.

Visión General¶

BotCity Runner proporciona una observabilidad integral a través de:

Logs Estructurados — Formato TEXT o JSON con metadatos contextuales detallados
Integración con OpenTelemetry — Exportación de logs a cualquier backend compatible con OTLP
Propagación de Contexto mediante MDC — Correlación consistente entre las entradas de log

Referencia de Configuración¶

Variables de Entorno¶

Variable	Predeterminado	Descripción
`BOTCITY_RUNNER_LOG_DIR`	`./logs`	Directorio para los archivos de log
`BOTCITY_RUNNER_LOG_FORMAT`	`TEXT`	Formato del log: `TEXT` o `JSON`
`BOTCITY_RUNNER_LOG_LEVEL`	`INFO`	Nivel de log del paquete `dev.botcity.runner`
`BOTCITY_RUNNER_LOG_CONSOLE`	`false`	Habilita la salida por consola
`BOTCITY_RUNNER_OTEL_ENABLED`	`false`	Habilita la exportación mediante OpenTelemetry

Variables de OpenTelemetry¶

Cuando BOTCITY_RUNNER_OTEL_ENABLED=true, el Runner respeta las variables de entorno estándar de OTEL:

Variable	Predeterminado	Descripción
`OTEL_EXPORTER_OTLP_ENDPOINT`	`http://localhost:4317`	URL del endpoint OTLP
`OTEL_EXPORTER_OTLP_HEADERS`	—	Cabeceras de autenticación (`key=value,key2=value2`)
`OTEL_EXPORTER_OTLP_PROTOCOL`	`grpc`	Protocolo: `grpc` o `http/protobuf`
`OTEL_EXPORTER_OTLP_COMPRESSION`	—	Compresión: `gzip` o `none`
`OTEL_EXPORTER_OTLP_TIMEOUT`	—	Tiempo de espera de la solicitud en milisegundos
`OTEL_SERVICE_NAME`	`botcity-runner`	Nombre del servicio para identificación
`OTEL_RESOURCE_ATTRIBUTES`	—	Atributos adicionales (`key=value,key2=value2`)

Campos de Contexto del Log¶

Cada entrada de log incluye metadatos contextuales mediante MDC (Mapped Diagnostic Context):

Campo	Descripción
`organization`	Identificador de la organización
`runnerLabel`	Etiqueta de la instancia del Runner
`runnerVersion`	Versión del software del Runner
`automationLabel`	Etiqueta de la automatización
`technology`	Tecnología del bot (Python, Java, etc.)
`botId`	Etiqueta/Identificador del Bot
`botVersion`	Versión del bot
`taskId`	Identificador de la tarea actual

Estos campos permiten el filtrado y la correlación entre sistemas distribuidos.

Formatos de Log¶

Formato TEXT (Predeterminado)¶

Formato legible por humanos, adecuado para el desarrollo local y la gestión 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 estructurado, compatible con plataformas de agregación 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"
}

Habilítalo con:

export BOTCITY_RUNNER_LOG_FORMAT=JSON

Integración con Plataformas de Observabilidad¶

BotCity Runner admite la integración directa con plataformas de observabilidad mediante OpenTelemetry. No se requiere ningún colector intermediario — el Runner envía los logs directamente a estos servicios.

Dynatrace¶

Dynatrace ofrece observabilidad full-stack con análisis impulsado 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

Pasos de configuración:

En Dynatrace, ve a Settings → Integration → API tokens
Crea un token con el alcance logs.ingest
Reemplaza {environment-id} con el ID de tu entorno Dynatrace
Reemplaza dt0c01.xxxxxxxxxxxx con tu token de API

Visualización de los logs:

Navega a Observe and explore → Logs
Filtra por service.name = "botcity-runner"
Usa DQL para consultar: fetch logs | filter service.name == "botcity-runner"

New Relic¶

New Relic ofrece observabilidad unificada con consultas potentes mediante 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

Pasos de configuración:

En New Relic, ve a API keys (menú de usuario → API keys)
Crea o copia tu License key (comienza con NRAK-)
Para el centro de datos de la UE, utiliza https://otlp.eu01.nr-data.net:4318

Visualización de los logs:

Navega a Logs
Filtra por service.name = "botcity-runner"
Usa NRQL: SELECT * FROM Log WHERE service.name = 'botcity-runner'

Consultas NRQL útiles:

-- Tasa de error por automatización
SELECT count(*) FROM Log 
WHERE service.name = 'botcity-runner' AND level = 'ERROR'
FACET automationLabel TIMESERIES

-- Línea de tiempo de la ejecución de la tarea
SELECT * FROM Log 
WHERE service.name = 'botcity-runner' AND taskId = '12345'
ORDER BY timestamp

Datadog¶

Datadog ofrece monitoreo integral con análisis de logs y correlación con 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

Pasos de configuración:

En Datadog, ve a Organization Settings → API Keys
Crea o copia una clave de API
Para el sitio de la UE, utiliza https://http-intake.logs.datadoghq.eu:443

Visualización de los logs:

Navega a Logs → Search
Filtra por service:botcity-runner
Crea facets para @taskId, @botId, @automationLabel para un filtrado eficiente

Consultas útiles:

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

Grafana Cloud¶

Grafana Cloud ofrece observabilidad basada en código abierto, con Loki para los 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

Pasos de configuración:

En Grafana Cloud, ve a tu stack → Connections → OpenTelemetry
Anota la URL del endpoint OTLP (varía según la región)
Crea un token de API con el alcance logs:write
Codifica instanceId:apiKey en Base64 para la cabecera Authorization:
```
echo -n "123456:glc_xxxxxxxxxxxx" | base64
```

Visualización de los logs:

Navega a Explore → Selecciona la fuente de datos Loki
Usa LogQL: {service_name="botcity-runner"}

Consultas LogQL útiles:

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

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

# Buscar por automatización
{service_name="botcity-runner"} | json | automationLabel="invoice-bot"

Uso de un OpenTelemetry Collector¶

Para escenarios avanzados (buffering, transformación, enrutamiento a múltiples destinos), despliega un OpenTelemetry Collector como intermediario.

Cuándo Utilizar un Collector¶

Enrutamiento a múltiples destinos — Envía logs a varios backends simultáneamente
Transformación de datos — Enriquece, filtra o redacta los datos de log
Buffering — Maneja las interrupciones de red de forma resiliente
Gestión de credenciales — Mantén las claves de API en el collector, no en el Runner

Configuración Básica del 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:
  # Ejemplo: Datadog
  datadog:
    api:
      key: ${DD_API_KEY}
      site: datadoghq.com

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

  # Ejemplo: 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 ]

Configura el Runner para enviar los logs al collector:

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

Mejores Prácticas¶

1. Utiliza una Nomenclatura de Servicio Consistente¶

Define OTEL_SERVICE_NAME de forma consistente en todas las instancias del Runner:

export OTEL_SERVICE_NAME=botcity-runner

Agrega contexto del entorno mediante atributos de recurso:

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

2. Habilita el Formato JSON para la Agregación de Logs¶

Al utilizar plataformas de agregación de logs sin OTEL, habilita el formato JSON:

export BOTCITY_RUNNER_LOG_FORMAT=JSON

Esto permite el análisis estructurado y la extracción de campos.

3. Estrategia de Retención de Logs¶

Considera tus necesidades de retención:

Archivos locales — 7 días, límite de 1GB (predeterminado)
Backend OTEL — Configura según los requisitos de cumplimiento

Solución de Problemas¶

Los Logs No Aparecen en el Backend¶

Verifica que OTEL esté habilitado:

echo $BOTCITY_RUNNER_OTEL_ENABLED  # Debe devolver "true"

Verifica la conectividad con el endpoint:
```
curl -v $OTEL_EXPORTER_OTLP_ENDPOINT
```
Verifica que las cabeceras de autenticación sean correctas
Revisa los logs de inicio del Runner en busca de errores de inicialización de OTEL

Campos de Contexto Ausentes¶

Asegúrate de que el Runner esté configurando correctamente el contexto MDC. Verifica que:

La ejecución de la tarea esté siguiendo la ruta de ejecución estándar
No estén ocurriendo excepciones antes de que se establezca el contexto

Alta Latencia o Logs Descartados¶

Si utilizas la integración directa:

Considera desplegar un collector para buffering
Verifica la latencia de red hasta el backend
Verifica que no se estén alcanzando los límites de tasa del backend

Comportamiento de Reintentos y Resiliencia¶

El SDK de OpenTelemetry incluye lógica de reintentos integrada para fallos transitorios al exportar logs:

Comportamiento Predeterminado¶

Configuración	Valor Predeterminado	Descripción
Reintentos habilitados	Sí	Reintento automático en caso de fallos transitorios
Backoff inicial	1 segundo	Tiempo de espera antes del primer reintento
Backoff máximo	5 segundos	Tiempo máximo de espera entre reintentos
Multiplicador de backoff	1.5	Factor de backoff exponencial
Máximo de intentos	5	Total de reintentos antes de descartar
Timeout de exportación	10 segundos	Timeout por solicitud (configurable mediante `OTEL_EXPORTER_OTLP_TIMEOUT`)

Qué Sucede Durante las Interrupciones¶

Interrupciones cortas (< 30 segundos) — Los logs se almacenan en buffer y se reintentan automáticamente
Interrupciones prolongadas — Tras los reintentos máximos, los logs se descartan (se registran localmente si el file appender está habilitado)
Apagado controlado — Al cerrar la JVM, el SDK descarga los logs pendientes antes de finalizar

Ajustes para Tu Entorno¶

Para redes de alta latencia o conexiones inestables:

# Aumentar el timeout de la solicitud (milisegundos)
export OTEL_EXPORTER_OTLP_TIMEOUT=30000

# Habilitar la compresión para reducir el consumo de ancho de banda
export OTEL_EXPORTER_OTLP_COMPRESSION=gzip

Para entornos de producción con requisitos estrictos de fiabilidad, considera desplegar un OpenTelemetry Collector como buffer local.

Observabilidad¶

Visión General¶

Referencia de Configuración¶

Variables de Entorno¶

Variables de OpenTelemetry¶

Campos de Contexto del Log¶

Formatos de Log¶

Formato TEXT (Predeterminado)¶

Formato JSON¶

Integración con Plataformas de Observabilidad¶

Dynatrace¶

New Relic¶

Datadog¶

Grafana Cloud¶

Uso de un OpenTelemetry Collector¶

Cuándo Utilizar un Collector¶

Configuración Básica del Collector¶

Mejores Prácticas¶

1. Utiliza una Nomenclatura de Servicio Consistente¶

2. Habilita el Formato JSON para la Agregación de Logs¶

3. Estrategia de Retención de Logs¶

Solución de Problemas¶

Los Logs No Aparecen en el Backend¶

Campos de Contexto Ausentes¶

Alta Latencia o Logs Descartados¶

Comportamiento de Reintentos y Resiliencia¶

Comportamiento Predeterminado¶

Qué Sucede Durante las Interrupciones¶

Ajustes para Tu Entorno¶

Referencias¶