Logging & Telemetry (OTLP)
Relevant source files
The following files were used as context for generating this wiki page:
The Logging and Telemetry system in the Poixpixel Discord Bot provides a robust, multi-layered approach to monitoring application state, user actions, and system health. It combines local console logging for development, rich Discord-based audit logs for moderation, and advanced OpenTelemetry (OTLP) integration for distributed tracing and centralized log management.
The system is built upon the winston logging library and utilizes OpenTelemetry SDKs to export logs via HTTP/JSON. This allows the bot to maintain high observability while providing administrators with actionable insights into server events like message edits, purges, and moderation actions.
System Architecture
The logging architecture consists of three primary components: the Winston logger (core), the Discord Action Logger (moderation-focused), and the OpenTelemetry Transport (telemetry).
The diagram above illustrates how application events are routed through different logging mechanisms based on their purpose—system monitoring or community moderation.
Sources: src/util/logger.ts:109-138, src/util/logging/logAction.ts:39-47
Core Logging System (Winston)
The bot uses winston as its primary logging engine. It supports nine custom log levels ranging from fatal (highest priority) to silly (lowest). The logger is initialized globally via initLogger() and includes specialized formatting for console output, including color-coded levels and pretty-printed metadata.
Log Levels
| Level | Priority | Description |
|---|---|---|
| fatal | 0 | System-level failures resulting in termination |
| crit | 1 | Critical issues requiring immediate attention |
| error | 2 | Runtime errors or failed operations |
| warn | 3 | Potential issues or degraded performance |
| info | 4 | Standard informational messages |
| http | 5 | Network-related logs |
| verbose | 6 | Detailed debugging information |
| debug | 7 | Low-level internal state details |
| silly | 8 | Extremely granular execution logs |
Sources: src/util/logger.ts:110-120, src/util/logger.ts:153-163
Global Error Handling
The initLogger function attaches listeners to uncaughtException and unhandledRejection. On a fatal exception, the system attempts to flush all transports (including the OTLP buffer) before exiting the process.
Sources: src/util/logger.ts:170-244
Discord Audit Logging
Managed by logAction.ts, this system translates bot and member events into rich Discord Embeds sent to a designated logs channel.
Logged Events
The system handles a wide variety of events, including:
- Moderation: Bans, kicks, mutes, warnings, and counting-specific punishments.
- Messages: Deletions and edits (including "Jump to Message" buttons).
- Members: Join/leave events and username/nickname updates.
- Roles/Channels: Creation, deletion, and complex permission updates.
Purge Logging Mechanism
When a purge action occurs, the system generates a detailed text file containing the content and metadata of all deleted messages. This file is temporarily stored in the OS temp directory, sent as a Discord attachment, and then deleted.
OpenTelemetry (OTLP) Integration
The OtelTransport class extends winston-transport to bridge Winston logs with the OpenTelemetry ecosystem. It maps standard Winston levels to the OpenTelemetry SeverityNumber and SeverityText specifications.
Mapping Winston to OTEL
| Winston Level | OTEL Severity Text | OTEL Severity Number |
|---|---|---|
| silly | TRACE | 2 |
| verbose / debug | DEBUG | 6 / 7 |
| info | INFO | 11 |
| warn | WARN | 14 |
| error | ERROR | 17 |
| fatal | FATAL | 24 |
Sources: src/util/telemetry/otelLogTransport.ts:24-42
Telemetry Configuration
Telemetry is configured via the telemetry.otel block in config.json. Key parameters include:
serviceName: The identifier for the bot in the telemetry collector.otlpEndpoint: The destination URL (e.g.,http://localhost:4318/v1/logs).batch: Configuration for theBatchLogRecordProcessor, controlling queue sizes and export delays.
Sources: config.example.json:141-177, src/util/telemetry/otelLogTransport.ts:98-121
Configuration Summary
The following configuration options control the behavior of the logging and telemetry systems.
| Option | Type | Default | Description |
|---|---|---|---|
telemetry.level | string | "info" | Minimum Winston log level to process |
telemetry.otel.enabled | boolean | false | Enables OpenTelemetry log exporting |
telemetry.otel.serviceName | string | "poixpixel-discord-bot" | Service name for OTEL resource |
telemetry.otel.otlpEndpoint | string | N/A | HTTP endpoint for OTLP logs |
channels.logs | Snowflake | N/A | Discord channel ID for audit logs |
Sources: config.example.json:141-177, src/util/logger.ts:123-138
Conclusion
The Logging & Telemetry system provides a comprehensive observability stack. By leveraging Winston for structured logging, OpenTelemetry for remote telemetry, and Discord's UI for moderation audit trails, the bot ensures that developers can debug system issues while moderators maintain oversight of community activity. The inclusion of OTLP support prepares the bot for production-scale monitoring in distributed environments.