Skip to content

Logging enhancements - #141

Merged
englishm merged 4 commits into
cloudflare:mainfrom
englishm-cloudflare:logging-tracing-migration
Feb 18, 2026
Merged

Logging enhancements#141
englishm merged 4 commits into
cloudflare:mainfrom
englishm-cloudflare:logging-tracing-migration

Conversation

@englishm-cloudflare

@englishm-cloudflare englishm-cloudflare commented Feb 5, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

  • Migrate from log crate to tracing across all moq-rs crates
  • Add structured fields to high-value log messages (namespace, track, error, etc.)
  • Add structured debug logging for all MoQT control messages (26 message types)
  • Add additional debug logging for troubleshooting announce lifecycle and track cache operations

Changes

1. Tracing Migration (391d0a4)

  • Replace all log::{trace,debug,info,warn,error}! macros with tracing:: equivalents (~200 call sites)
  • Update workspace and crate Cargo.toml files to use tracing instead of log/env_logger
  • Update binary main.rs files to use tracing_subscriber with env filter

2. Structured Fields (d39e98e)

  • Add structured tracing fields to key log messages in moq-relay-ietf
  • Fields like namespace, track, error, source, relay_url, origin_url

3. Control Message Logging (8bb7a07)

  • Add log_control_message() helper in moq-transport/src/session/mod.rs
  • Comprehensive logging for all 26 MoQT control message types
  • Uses custom target moq_transport::control for independent filtering
  • Structured fields: direction ("sent"/"recv"), msg_type, plus message-specific fields

4. Additional Debug Logging (9cfa730)

  • Announce lifecycle: coordinator registration, locals registration, ANNOUNCE_OK
  • Announce closed events and locals deregistration
  • Track cache operations (hit/miss/stale eviction) with target moq_transport::tracks
  • Track close and state drop events (helps debug Cancel errors)

Filtering Examples

# Default (info level)
RUST_LOG=info ./dev/relay

# Enable control message logging
RUST_LOG=info,moq_transport::control=debug ./dev/relay

# Enable track cache logging
RUST_LOG=info,moq_transport::tracks=debug ./dev/relay

# Enable all debug logging
RUST_LOG=debug ./dev/relay

Sample Output

DEBUG moq_transport::control: MoQT control message direction="recv" msg_type="CLIENT_SETUP" versions=Versions([DRAFT_14])
DEBUG moq_transport::control: MoQT control message direction="sent" msg_type="SERVER_SETUP" version=DRAFT_14
DEBUG moq_transport::control: MoQT control message direction="recv" msg_type="PUBLISH_NAMESPACE" request_id=0 namespace=/bbb
DEBUG registering namespace with coordinator namespace=/bbb
DEBUG namespace registered with coordinator namespace=/bbb
DEBUG registering namespace in locals namespace=/bbb
DEBUG sent ANNOUNCE_OK namespace=/bbb
DEBUG moq_transport::tracks: track cache miss, requested from upstream namespace=/bbb track=0.mp4

Testing

  • Verified compilation and tests pass
  • Tested relay with publisher/subscriber to confirm logging appears correctly
  • Verified filtering works as expected
@englishm englishm changed the title refactor: migrate from log to tracing with structured logging Feb 5, 2026
@englishm
refactor: migrate from log crate to tracing
ea287ac 
Replace the log crate with tracing throughout the codebase as Phase 1
of the logging/tracing migration. This aligns moq-rs with the broader
Rust ecosystem (tokio, hyper, axum) and enables future enhancements
like structured fields and spans.

Changes:
- Replace all log::{trace,debug,info,warn,error}! macros with tracing equivalents
- Update Cargo.toml files to use tracing and tracing-subscriber
- Remove log and env_logger dependencies from workspace
- Update binary main.rs files to use tracing_subscriber::fmt() with EnvFilter
- Default log filter: info level with quinn=warn to suppress QUIC noise

Backward compatible:
- RUST_LOG environment variable still works
- Output destination unchanged (stdout/stderr)
- Log message format unchanged for this phase
@englishm
feat: add structured fields to high-value log messages
2855ab7 
Add structured tracing fields (namespace, track, error, source, etc.)
to log messages in moq-relay-ietf while preserving the original message
format for backward compatibility with existing text-based searches.

This enables:
- Filtering logs by namespace/track in Elasticsearch
- Structured queries without breaking existing workflows
- Easier debugging by having key identifiers as separate JSON fields

Files updated:
- consumer.rs: announce/subscribe flows
- producer.rs: subscribe/track_status handling
- relay.rs: session error handling
- remote.rs: remote origin handling
- file_coordinator.rs: namespace registration
- api_coordinator.rs: API-based coordination

The message body remains unchanged - fields are duplicated in both
the message string and as separate structured fields.
@englishm
feat: add structured debug logging for MoQT control messages
fafbce0 
Add debug-level tracing logs for all MoQT control messages sent and
received on the control stream. Each log includes:
- direction: 'sent' or 'recv'
- msg_type: message type name (e.g., SUBSCRIBE, PUBLISH_NAMESPACE_OK)
- Message-specific fields matching the mlog schema

Uses custom target 'moq_transport::control' so these logs can be
filtered independently via tracing-subscriber's EnvFilter. This
allows applications like crique to enable these logs in production
while keeping moq-transport quiet by default for other users.

Control messages logged:
- Setup: CLIENT_SETUP, SERVER_SETUP
- Subscribe family: SUBSCRIBE, SUBSCRIBE_OK, SUBSCRIBE_ERROR,
  SUBSCRIBE_UPDATE, UNSUBSCRIBE
- PublishNamespace family: PUBLISH_NAMESPACE, PUBLISH_NAMESPACE_OK,
  PUBLISH_NAMESPACE_ERROR, PUBLISH_NAMESPACE_DONE,
  PUBLISH_NAMESPACE_CANCEL
- TrackStatus family: TRACK_STATUS, TRACK_STATUS_OK, TRACK_STATUS_ERROR
- SubscribeNamespace family: SUBSCRIBE_NAMESPACE,
  SUBSCRIBE_NAMESPACE_OK, SUBSCRIBE_NAMESPACE_ERROR,
  UNSUBSCRIBE_NAMESPACE
- Fetch family: FETCH, FETCH_OK, FETCH_ERROR, FETCH_CANCEL
- Publish family: PUBLISH, PUBLISH_OK, PUBLISH_ERROR, PUBLISH_DONE
- Session: GOAWAY, MAX_REQUEST_ID, REQUESTS_BLOCKED
@englishm
feat: add additional debug logging for troubleshooting
33b7499 
Add logging for:
- Announce lifecycle (coordinator registration, locals registration, ANNOUNCE_OK)
- Announce closed events
- Locals deregistration on drop
- Track cache operations (hit/miss/stale eviction)
- Track close and state drop events

Track cache logging uses target 'moq_transport::tracks' for independent filtering.
@englishm
englishm merged commit bdbcc65 into cloudflare:main Feb 18, 2026
1 check passed
@kkroo kkroo mentioned this pull request Jul 19, 2026
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

4 participants

@englishm-cloudflare @nnazo @itzmanish @englishm