Logging and Telemetry

Relevant source files

The following files were used as context for generating this wiki page:

• src/utils/writeToLog.ts
• src/utils/telemetry.ts
• src/app.ts
• src/env.ts
• package.json
• stt/src/main.rs
• src/processors/recordAudio.ts

The discord-live-translator project incorporates two primary mechanisms for observability: a standard logging system for operational output and a telemetry system for analytics and usage tracking. The standard logging provides real-time feedback for developers and system administrators, capturing key events like audio recording, translation processes, and bot status changes. This is written to the console and optionally to a log file.

For user-centric analytics, the application integrates with PostHog. This allows for tracking user interactions, such as command usage, to understand how the bot is being used. This telemetry is conditional and only active if the appropriate environment variables are configured. The system also includes logging within its separate Rust-based Speech-to-Text (STT) service.

Standard Logging

The primary logging mechanism is a custom utility function that writes timestamped messages to the console and, if configured, to a persistent log file. This is used throughout the TypeScript application to trace the execution flow and debug issues.

Sources: src/utils/writeToLog.ts, src/app.ts, src/processors/recordAudio.ts

writeToLog Utility

The core of the logging system is the writeToLog function. It is designed to be a simple yet effective logger.

• Functionality: It accepts one or more string arguments, joins them into a single message, prepends a UTC timestamp in ISO format, and logs the result to the console.
• File Logging: If the LOG_PATH environment variable is set, the function will also asynchronously append the same timestamped message to the specified file path. The path can be absolute or relative to the current working directory.
• Error Handling: Errors during the file-append operation are caught and logged to the console without crashing the application.

Sources: src/utils/writeToLog.ts:6-16, src/env.ts:13

The following diagram illustrates the flow of the writeToLog function.

Usage Examples

The writeToLog function is used in various parts of the application to signal important events.

• Application Lifecycle: On startup, it logs the bot's tag once it's ready.
  • writeToLog(\Logged in as ${client.user.tag}!`);`
  • Sources: src/app.ts:49
• Audio Processing: It logs the start and end of audio recording sessions, including the user ID and the temporary file name.
  • writeToLog(\Started recording ${userId} to ${fileName}`);`
  • Sources: src/processors/recordAudio.ts:34

Rust STT Service Logging

The separate Speech-to-Text (STT) service, written in Rust, uses the simple_logger and log crates for its logging. It is initialized from environment variables and logs information such as server startup.

• simple_logger::init_with_env().unwrap();
• log::info!("Starting server at http://127.0.0.1:8000");

Sources: stt/src/main.rs:64, stt/src/main.rs:71, stt/Cargo.toml:11-12

Telemetry (PostHog)

For analytics and usage tracking, the application uses the posthog-node library. This is an optional feature, enabled only when PostHog credentials are provided in the environment configuration.

Sources: src/utils/telemetry.ts, package.json:28

Initialization

The PostHog client is initialized in src/utils/telemetry.ts.

• A new PostHog client instance is created if POSTHOG_API_KEY is present in the environment.
• The POSTHOG_HOST can also be configured, with a default value of https://app.posthog.com.
• If the API key is not provided, the client object is null, and all tracking calls are effectively no-ops.

Sources: src/utils/telemetry.ts:5-9, src/env.ts:14-15

Event Tracking

The trackEvent function is the primary interface for sending telemetry data.

• trackEvent(source, event): This function captures an event.
  • source: An object containing userId and guildId. The userId is used as the distinctId in PostHog, and guildId is used to group events by server.
  • event: An object with a name and a properties payload.
• Example: When a user executes a slash command, a Command Used event is tracked with the command name as a property. This happens in the main interactionCreate event listener.

The diagram below shows the sequence of a user command triggering a telemetry event.

Graceful Shutdown

To ensure that all buffered telemetry events are sent before the application exits, a shutdown handler is implemented.

• The flushEvents function calls client.shutdown() on the PostHog instance.
• This handler is registered for SIGTERM and SIGINT process signals, which are common signals for stopping a process in containerized or managed environments.

Sources: src/app.ts:92-97, src/utils/telemetry.ts:24-28

Configuration

Logging and telemetry behavior is controlled via environment variables defined in src/env.ts.

Variable	Type	Description
LOG_PATH	string (optional)	If set, logs will be appended to this file path.
POSTHOG_API_KEY	string (optional)	The API key for PostHog. If not set, telemetry is disabled.
POSTHOG_HOST	string (optional)	The PostHog instance host. Defaults to https://app.posthog.com.
HEARTBEAT_URL	string (optional)	A URL to send a POST request to every 60 seconds as a health check. Failures are logged to the console.

Sources: src/env.ts:13-16, src/env.ts:19

Summary

The project employs a two-tiered approach to observability. A straightforward, file-based logging system (writeToLog) provides essential operational data for debugging and monitoring the bot's internal state. This is complemented by an optional, more advanced telemetry system using PostHog (trackEvent) to gather analytics on user engagement with bot commands. This separation allows for detailed developer-focused logs while collecting high-level usage metrics for product improvement, with both systems being configurable via environment variables.