Debugging¶

Logging System Overview¶

Shaka Packager uses the Google logging library (glog) which provides three types of logging mechanisms:

LOG() - Standard severity-based logging (INFO, WARNING, ERROR, FATAL)
VLOG() - Global verbose logging with numeric levels
DVLOG() - Per-module debug verbose logging with numeric levels

Understanding the differences between these logging types is essential for effective debugging without being overwhelmed by log output.

Logging Types Comparison¶

Type	Control Flag	Default Behavior	Purpose
LOG(INFO/WARNING/ERROR)	`--minloglevel`	Always shown	Standard production logging
VLOG(N)	`--v=N`	Hidden (off)	Global verbose debugging
DVLOG(N)	`--vmodule=module=N`	Hidden (off)	Per-module verbose debugging

Standard Logging (LOG)¶

Standard LOG statements are used for production logging and are always enabled by default. They use severity levels to indicate the importance of messages.

Severity Levels¶

LOG(INFO) - Informational messages (routine operations, status updates)
LOG(WARNING) - Warning messages (potential issues, degraded functionality)
LOG(ERROR) - Error messages (recoverable errors, failed operations)
LOG(FATAL) - Fatal errors (unrecoverable errors, terminates program)

Controlling LOG Output¶

Use --minloglevel=N to set the minimum severity level to display:

# Show only WARNING and above (hide INFO messages)
$ packager input.ts --minloglevel=1

# Show only ERROR and above (hide INFO and WARNING)
$ packager input.ts --minloglevel=2

# Show everything (default)
$ packager input.ts --minloglevel=0

Severity level values:

0 = INFO and above (default)
1 = WARNING and above
2 = ERROR and above
3 = FATAL only

Other useful LOG flags:

# Send logs to stderr in addition to log files
$ packager input.ts --alsologtostderr

# Set which logs go to stderr (0=INFO, 1=WARNING, 2=ERROR)
$ packager input.ts --stderrthreshold=1

Verbose Logging (VLOG and DVLOG)¶

VLOG and DVLOG provide detailed diagnostic logging that is silent by default. These are essential for debugging specific components without cluttering production output.

Verbosity Levels¶

Both VLOG and DVLOG use numeric levels to control detail:

Level 1: High-level events (initialization, major state changes)
Level 2: Medium detail (sample/packet processing, typical debugging)
Level 3: Detailed tracing (internal operations, verbose debugging)
Level 4: Very detailed tracing (fine-grained internal operations)

Higher levels include all messages from lower levels (e.g., level 2 includes level 1 messages).

VLOG - Global Verbose Logging¶

VLOG affects ALL modules in the entire application. Use this when you want general verbose output from the whole system:

# Enable all VLOG(1) and VLOG(2) statements everywhere
$ packager input.ts --v=2

# Enable only VLOG(1) statements everywhere
$ packager input.ts --v=1

Warning: Using high VLOG levels (–v=3 or –v=4) can produce very large amounts of output and may impact performance.

DVLOG - Per-Module Debug Logging¶

DVLOG (Debug Verbose LOG) allows selective enabling for specific modules only. This is the recommended approach for targeted debugging:

# Enable logging for teletext parser only
$ packager input.ts --vmodule=es_parser_teletext=2

# Enable logging for multiple modules
$ packager input.ts --vmodule=es_parser_teletext=2,text_chunker=1

# Combine global and module-specific levels
$ packager input.ts --v=1 --vmodule=mp2t_media_parser=3

Module names correspond to source file names without extensions (e.g., es_parser_teletext for es_parser_teletext.cc). Glob patterns with * and ? are supported.

Practical Examples¶

Debugging Teletext Heartbeat Feature¶

To debug the teletext heartbeat mechanism with detailed logging from only the relevant modules:

$ packager \
  'in=input.ts,stream=text,cc_index=888,output=out.vtt' \
  --vmodule=es_parser_teletext=2,text_chunker=2,mp2t_media_parser=2

This enables:

es_parser_teletext=2: Shows heartbeat emission (kTextHeartBeat, kCueStart, kCueEnd)
text_chunker=2: Shows heartbeat processing and segment dispatch
mp2t_media_parser=2: Shows media heartbeat generation from video PTS

Clean Output with Minimal Noise¶

To see only warnings/errors plus specific debug output:

$ packager input.ts \
  --minloglevel=1 \
  --vmodule=text_chunker=2

This hides routine INFO messages while showing WARNING/ERROR messages and detailed text_chunker debug output.

Debugging Segment Output¶

To see when segments are created and written to disk:

$ packager input.ts \
  --vmodule=text_chunker=2,mp4_muxer=2 \
  --v=1

text_chunker=2 shows segment dispatch (DVLOG)
--v=1 enables mp4_muxer segment finalization logs (VLOG)

Full Debug Output¶

For comprehensive debugging (use cautiously, generates large output):

$ packager input.ts --v=3

This enables all VLOG statements at level 3 across the entire application.

Best Practices¶

Start with DVLOG: Use --vmodule to target specific modules rather than enabling global verbose logging with --v.
Suppress routine INFO: Add --minloglevel=1 to hide routine INFO messages when debugging, making it easier to spot relevant debug output.
Use appropriate levels: Start with level 1 or 2 for most debugging. Only use level 3+ when you need very detailed internal tracing.
Combine strategically: You can combine LOG control with VLOG/DVLOG:
```
$ packager input.ts --minloglevel=1 --vmodule=my_module=2
```
This shows only warnings/errors globally, plus detailed debug from my_module.
Save output to file: When using verbose logging, redirect to a file for easier analysis:
```
$ packager input.ts --vmodule=text_chunker=3 2>&1 | tee debug.log
```

Useful Modules for Debugging¶

Common modules that are useful to debug:

es_parser_teletext - Teletext parsing and subtitle extraction
text_chunker - Text segmentation and cue processing
mp2t_media_parser - MPEG-2 TS parsing and PID handling
mp4_muxer - MP4 segment creation and finalization
chunking_handler - General media chunking/segmentation
webvtt_to_mp4_handler - WebVTT to MP4 conversion
ts_muxer - MPEG-2 TS muxing

Use --vmodule=module_name=2 to enable debugging for any of these modules.