Skip to content

Monitoring Translations

This guide explains how to monitor translation jobs and troubleshoot processing issues using Symfony Messenger.

Monitoring Overview

What to Monitor

  • Job status: Overall translation job progress
  • Item status: Individual content piece progress
  • Message queue: Symfony Messenger processing status
  • Error rates: Failed vs successful translations
  • Processing time: How long translations take to complete

Where to Monitor

  • TMGMT interface: Job and item status in Drupal UI
  • Drupal logs: Error messages and processing information
  • Command line: Drush commands for quick status checks
  • Message queue: Messenger transport status (production)

Job Status Monitoring

Using the TMGMT Interface

  1. Go to Configuration → Translation Management → Jobs (/admin/config/regional/tmgmt_job)
  2. Click on any job to see detailed status:
  3. Job status: Submitted → Active → Completed/Rejected
  4. Item count: Total items and their individual statuses
  5. Messages: Any error messages or progress notes
  6. Created/Updated timestamps: Track processing duration

Understanding Item Statuses

Each job contains multiple items with these possible states: - Active: Currently being processed by Symfony Messenger - Needs Review: Translation completed, awaiting human review - Completed: Successfully imported and ready for use - Aborted: Processing was stopped (manual intervention) - Rejected: Failed to translate (error details available)

Status Flow Diagram

flowchart TD
    A[Job Submitted] --> B[Items Dispatched to Messenger]
    B --> C[Items in Active State]
    C --> D{Processing Complete?}
    D -->|Yes| E[Item Completed]
    D -->|Transient Error| F[Auto Retry via Messenger]
    D -->|Permanent Error| G[Item Rejected]
    E --> H[Ready for Review/Publish]
    F --> C

Message Queue Monitoring

Checking Messenger Status

# Check if messenger commands are available
drush list | grep messenger

# View message queue status (if configured)
drush messenger:info

# Process messages manually (for testing)
drush messenger:consume async --limit=10

Understanding Queue States

  • Messages in transit: Currently being processed by handlers
  • Retries pending: Failed messages waiting for retry
  • Processed count: Successfully handled messages
  • Failed count: Messages that exceeded retry limits

Production Queue Monitoring

For production deployments, consider setting up: - Transport dashboards: Redis/Dashboards for message queues - Monitoring alerts: Notifications for queue depth thresholds - Health checks: Automated tests for message processing

Log Monitoring

Drupal Log Viewing

  1. Go to Reports → Recent log messages (/admin/reports/dblog)
  2. Filter by Type = tmgmt_laratranslate
  3. Look for these key message types:
  4. Info: Normal processing progress
  5. Warning: Transient errors and retries
  6. Error: Permanent failures or configuration issues

Command Line Log Monitoring

# Show recent tmgmt_laratranslate logs
drush watchdog:show --type=tmgmt_laratranslate

# Follow logs in real-time
drush watchdog:tail --type=tmgmt_laratranslate

# Show error logs only
drush watchdog:show --severity=error --type=tmgmt_laratranslate

Important Log Messages

Watch for these specific messages: - "Processing job item @id via Symfony Messenger": Normal processing - "Transient error... Will retry": Temporary issue, will auto-retry - "Permanent error processing job item @id": Manual intervention needed - "Translation quota exceeded": API quota management needed

Performance Monitoring

Key Metrics to Track

  • Job completion rate: Percentage of jobs that finish successfully
  • Average processing time: How long jobs take from submission to completion
  • Queue depth: Number of pending translation messages
  • Retry rate: Percentage of items that need retry

Drush Performance Commands

# Check current queue depth
drush messenger:stats

# View active message handlers
drush messenger:list-handlers

# Monitor resource usage (if available)
drush status --format=json | jq '.["tmgmt-laratranslate"]'

Performance Optimization

If you see slow processing: 1. Check queue configuration: Ensure messenger transports are properly set up 2. Monitor API response times: Lara API latency issues 3. Review content size: Large content takes longer to process 4. Adjust worker processes: More workers for high volume

Alerting and Notifications

Setting Up Alerts

While not built-in, you can set up monitoring:

Log-Based Alerts

# Script to check for errors (example)
#!/bin/bash
ERRORS=$(drush watchdog:show --severity=error --type=tmgmt_laratranslate --format=csv | wc -l)
if [ $ERRORS -gt 0 ]; then
    echo "Alert: $ERRORS translation errors found"
    # Send notification logic here
fi

Queue Depth Monitoring

# Monitor message queue (if using database transport)
mysql -u user -p -e "SELECT COUNT(*) FROM messenger_messages WHERE queue='async'"
  • Daily reports: Job completion statistics
  • Real-time alerts: Critical error notifications
  • Weekly reviews: Performance trend analysis
  • Monthly summaries: Volume and quality reports

Troubleshooting Common Issues

Jobs Not Processing

Symptoms: Jobs stay in "Submitted" state indefinitely

Checks: 1. Verify Symfony Messenger module is enabled 2. Check message handler registration 3. Confirm messenger transport configuration

Commands:

# Check module status
drush pm:status | grep -E "(messenger|sm)"

# Verify handler registration
drush messenger:list-handlers | grep TranslationJobMessageHandler

High Failure Rates

Symptoms: Many jobs rejected or failing

Diagnostics:

# Check recent errors
drush watchdog:show --severity=error --type=tmgmt_laratranslate --limit=20

# Check API credential issues
drush config:get tmgmt_laratranslate.settings

Common Causes: - Expired Lara API credentials - Unsupported language mappings - Network connectivity issues - API quota exhaustion

Slow Processing

Symptoms: Jobs take much longer than expected

Investigation: 1. Monitor message queue depth 2. Check API response times 3. Review content complexity/size 4. Verify worker process allocation

Advanced Monitoring

Custom Monitoring Scripts

Create custom monitoring for your specific needs:

Status Dashboard Script

#!/bin/bash
echo "=== TMGMT Lara Translate Status ==="
echo "Active Jobs: $(drush tmgmt-job:list --status=active --format=yaml | yq '. | length')"
echo "Pending Messages: $(drush messenger:stats | jq '.pending')"
echo "Recent Errors: $(drush watchdog:show --severity=error --type=tmgmt_laratranslate --limit=1 --format=yaml | yq '. | length')"

Health Check Script

<?php
// Custom PHP health check
$job_storage = \Drupal::entityTypeManager()->getStorage('tmgmt_job');
$active_jobs = $job_storage->loadByProperties(['state' => 'active']);
echo "Active translation jobs: " . count($active_jobs);
?>