---
title: Debug Video Logging - Complete End-to-End Reference
type: note
permalink: documentation/debug-video-logging-complete-end-to-end-reference
tags:
- logging
- debug-video
- backend
- kinemotion
- monitoring
---

[{"text": "# Debug Video Logging - Complete End-to-End View\n\n## 1. BACKEND LOGS (Cloud Run) - AnalysisService\nFile: `backend/src/kinemotion_backend/services/analysis_service.py`\n\n### Request Lifecycle Logs:\n```\nvalidating_video_file\n↓\nvalidating_video_file_completed (duration_ms)\n↓\nvalidating_jump_type\n↓\nvalidating_jump_type_completed (duration_ms)\n↓\ngenerating_storage_key\n↓\ngenerating_storage_key_completed (duration_ms)\n↓\nsaving_uploaded_file\n↓\nsaving_uploaded_file_completed (file_size_mb, duration_ms)\n↓\ndebug_video_path_created (if debug=true)\n↓\nvideo_processing_started\n↓\n[KINEMOTION LIBRARY LOGS HAPPEN HERE]\n↓\nvideo_processing_completed (total_duration_s, duration_ms)\n↓\n[Individual stage timings logged, e.g., \"debug_video_generation\", \"debug_video_ffmpeg_reencoding_complete\"]\n↓\nuploading_original_video\n↓\noriginal_video_uploaded (url)\n↓\nuploading_analysis_results\n↓\nr2_results_upload (duration_ms, url, key)\n↓\nuploading_debug_video (if debug video exists)\n↓\nr2_debug_video_upload (duration_ms, url, key)\n│ OR\n└─ debug_video_empty_skipping_upload\n↓\nresponse_serialization (duration_ms)\n↓\ncleaning_up_temporary_files\n↓\ntemp_file_cleanup (duration_ms)\n↓\nvideo_analysis_completed (jump_type, duration_ms, metrics_count)\n```\n\n### What Each Log Shows:\n\n| Log Event | Information | Use Case |\n|-----------|-------------|----------|\n| `validating_video_file_completed` | Input validation time | File format check |\n| `saving_uploaded_file_completed` | File size, save duration | Upload performance |\n| `debug_video_path_created` | Temp file path | Debug enabled confirmation |\n| `video_processing_started/completed` | Full processing time | Total analysis duration |\n| `uploading_debug_video` | Starting debug upload | Confirms video was created |\n| `r2_debug_video_upload` | Duration, URL, key | Upload performance, storage location |\n| `debug_video_empty_skipping_upload` | Warning | Debug video was empty/failed |\n| `video_analysis_completed` | Total time, metric count | Full request summary |\n\n## 2. KINEMOTION LIBRARY LOGS - debug_overlay_utils.py\n\nThese logs appear WITHIN the backend's video processing step:\n\n```\nvideo_processing_started (BACKEND)\n↓\n─── KINEMOTION LOGS ───\n|\n├─ debug_video_codec_selected (codec, dimensions, fps)\n│\n├─ debug_video_resolution_optimized OR debug_video_resolution_native\n│  └─ (if > 720p: original=%sx%s, optimized=%sx%s, scale=%.2f)\n│\n├─ debug_overlay_renderer_initialized (source, output, fps)\n│\n├─ [Frame writing loop - no logs for each frame]\n│\n├─ debug_video_writer_released (path, codec)\n│\n├─ debug_video_ffmpeg_reencoding_start (if mp4v used)\n│  └─ (input, output, codec=libx264, pix_fmt=yuv420p)\n│\n├─ debug_video_ffmpeg_reencoding_complete (duration_ms)\n│\n├─ debug_video_reencoded_file_replaced (path, final_codec, pix_fmt)\n│  OR\n└─ debug_video_ffmpeg_not_available (codec, warning)\n   OR\n└─ debug_video_ready_for_playback (codec, path)\n─── END KINEMOTION LOGS ───\n↓\nvideo_processing_completed (BACKEND)\n```\n\n## 3. COMPLETE LOG FLOW EXAMPLE\n\nWhen user uploads a video with debug enabled:\n\n```json\n// BACKEND LOGS\n{\"event\": \"validating_video_file\", \"timestamp\": \"2025-12-19T10:30:00Z\"}\n{\"event\": \"validating_video_file_completed\", \"duration_ms\": 45.2}\n{\"event\": \"saving_uploaded_file_completed\", \"file_size_mb\": 125.45, \"duration_ms\": 892.3}\n{\"event\": \"debug_video_path_created\", \"debug_video_path\": \"/tmp/xyz.mp4\"}\n{\"event\": \"video_processing_started\"}\n\n  // KINEMOTION LIBRARY LOGS\n  {\"event\": \"debug_video_codec_selected: codec=h264, dimensions=1920x1080, fps=60.0\"}\n  {\"event\": \"debug_video_resolution_optimized: original=1920x1080, optimized=1280x720, scale=0.67\"}\n  {\"event\": \"debug_overlay_renderer_initialized: source=1920x1080, output=1280x720, fps=60.0\"}\n  {\"event\": \"debug_video_writer_released: path=/tmp/xyz.mp4, codec=h264\"}\n  {\"event\": \"debug_video_ready_for_playback: codec=h264, path=/tmp/xyz.mp4\"}\n\n{\"event\": \"video_processing_completed\", \"total_duration_s\": 45.23, \"duration_ms\": 45230.1}\n{\"event\": \"uploading_debug_video\", \"storage_key\": \"debug_videos/user@example.com/2025/12/19/abc123_debug.mp4\"}\n{\"event\": \"r2_debug_video_upload\", \"duration_ms\": 3456.2, \"url\": \"https://r2.../abc123_debug.mp4\", \"key\": \"...\"}\n{\"event\": \"video_analysis_completed\", \"jump_type\": \"cmj\", \"duration_ms\": 50234.5}\n```\n\n## 4. WHERE TO FIND LOGS\n\n### Development (Local)\n- **Terminal Output**: Both backend and kinemotion logs print to stdout\n- **Format**: Human-readable with colors\n- **Access**: Check your terminal/IDE console\n\n### Production (Cloud Run)\n- **Location**: Google Cloud Logging\n- **URL**: https://console.cloud.google.com/logs\n- **Format**: JSON structured logs\n- **Filter**: \n  ```\n  resource.type=\"cloud_run_revision\"\n  event=\"r2_debug_video_upload\" OR event=\"debug_video_codec_selected\"\n  ```\n\n## 5. KEY METRICS TO MONITOR\n\n| Metric | Log Event | What It Means |\n|--------|-----------|---------------|\n| Total Duration | `video_analysis_completed` | End-to-end processing time |\n| FFmpeg Duration | `debug_video_ffmpeg_reencoding_complete` | Re-encoding overhead |\n| Upload Duration | `r2_debug_video_upload` | Network/storage performance |\n| File Size | `saving_uploaded_file_completed` | Input video size |\n| Codec Used | `debug_video_codec_selected` or `debug_video_ready_for_playback` | Video format |\n| Resolution | `debug_video_resolution_optimized` | Actual output dimensions |\n\n## 6. TROUBLESHOOTING WITH LOGS\n\n### Debug video not appearing:\n1. Check: `debug_video_path_created` - was path created?\n2. Check: `debug_video_ready_for_playback` - did codec selection succeed?\n3. Check: `r2_debug_video_upload` - did upload complete?\n4. If missing: `debug_video_empty_skipping_upload` - video was empty\n\n### Slow uploads:\n1. Check: `debug_video_ffmpeg_reencoding_complete` - how long did re-encoding take?\n2. Check: `r2_debug_video_upload` duration_ms - how long was upload?\n3Check: `saving_uploaded_file_completed` - input file size\n\n### Codec issues:\n1. Check: `debug_video_codec_selected` - which codec was chosen?\n2. Check: If h264 failed, check if mp4v fallback was used\n3. Check: `debug_video_ffmpeg_not_available` - is ffmpeg available?\n\n## 7. INTEGRATION NOTES\n\n- **Logging Library**: Backend uses `structlog` with standard `logging` module\n- **Kinemotion Library**: Uses standard `logging.getLogger(__name__)`\n- **Compatibility**: Both work seamlessly together\n- **Log Level**: Can be controlled via LOG_LEVEL env var (INFO by default)\n- **JSON Output**: Enabled in production via JSON_LOGS env var\n", "type": "text"}]
