messenger-logger-callback

messenger-logger-callback (messenger_logger_callback) — a Python library for sending training logs to a remote server with real-time Telegram notifications. Works as a standalone logger for any training loop (PyTorch, Lightning, custom) or as a Hugging Face Trainer Callback.

Pairs with telegram-log-service for real-time Telegram bot alerts, metric monitoring, and stalled run detection.

Installation

pip install messenger-logger-callback

Or equivalently:

pip install messenger_logger_callback

This installs everything including Hugging Face Transformers Trainer support. If you only need the standalone logger and want to avoid the transformers dependency, install with --no-deps and add requests and python-dotenv manually.

Quick Start: Standalone Logger

Use MessengerLogger in any training loop — plain PyTorch, Lightning, or anything else.

from messenger_logger import MessengerLogger

logger = MessengerLogger(
    server_url="http://your-server:5000/api/logs",
    project_name="resnet_experiment",
    run_id="run_v3",
    author_username="riko",
)

logger.start()

for epoch in range(num_epochs):
    for step, batch in enumerate(dataloader):
        loss = train_step(batch)
        global_step += 1
        logger.log(step=global_step, epoch=epoch, metrics={"loss": loss.item()})
    logger.epoch_end(epoch)

logger.finish()

Available Methods

Quick Start: Hugging Face Trainer

Use MessengerLoggerCallback as a drop-in Trainer callback.

from transformers import Trainer, TrainingArguments
from messenger_logger.callback import MessengerLoggerCallback

logger = MessengerLoggerCallback(
    server_url="http://your-server:5000/api/logs",
    project_name="bert_finetune",
    run_id="experiment_v2",
    auth_token="your_secret_token",
    author_username="riko",
    metadata={"model": "bert-large", "dataset": "squad"},
)

trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=train_dataset,
    callbacks=[logger],
)
trainer.train()

The callback automatically captures on_log, on_train_begin, on_train_end, and on_epoch_end events.

You can also send custom data at any point:

logger.send_custom_log({
    "event": "evaluation_complete",
    "accuracy": 0.95,
    "f1": 0.93,
})

Heartbeat

A background thread sends a lightweight heartbeat signal to the server every 60 seconds by default. This allows the server to detect crashed or stalled runs much faster than waiting for missing log events.

• On by default with a 60-second interval.
• Starts when training begins, stops when training ends.
• If the training process crashes, the heartbeat stops automatically.

To change the interval or disable:

# Custom interval (30 seconds)
logger = MessengerLogger(server_url="...", heartbeat_interval=30)

# Disable heartbeat
logger = MessengerLogger(server_url="...", heartbeat_interval=None)

ClearML Integration

If ClearML is active in your training script, the library automatically detects the current task and includes a link to the ClearML dashboard in every payload sent to the server. No configuration needed — if clearml is installed and a task is running, the link is captured.

Configuration

Settings can be provided via constructor arguments, environment variables, or a .env file. Constructor arguments take highest precedence, then environment variables, then .env file values.

Error Handling

Network errors (timeouts, connection failures, HTTP errors) are caught and printed as warnings. They never crash your training. Example messages:

Warning: Request to http://... timed out for step 10.
Error: Could not connect to server at http://... for step 20.
Error: HTTP error occurred while sending logs for step 30. Status: 401.

Related Projects

• telegram-log-service — the server that receives logs from this library and forwards them as Telegram bot alerts.

License

MIT

_{messenger-logger-callback · messenger_logger_callback · pip install messenger-logger-callback · pip install messenger_logger_callback · Telegram training logger · Hugging Face Trainer callback logger · ML training Telegram notifications}