Logging and Debugging

YouTrack CLI features a comprehensive logging system built with structlog and rich to help with debugging, monitoring, and troubleshooting operations.

Overview

The logging system provides:

Structured logging with contextual information
Multiple log levels for different verbosity needs
File-based logging with automatic rotation
Console logging with rich formatting
Sensitive data masking for security
API call tracking with performance metrics

Log Levels

Control the verbosity of output using these options:

Basic Options

# Basic verbose output (INFO level)
yt --verbose issues list

# Debug output with detailed information
yt --debug issues list

Advanced Level Control

# Set specific log level
yt --log-level ERROR issues list
yt --log-level DEBUG issues list

# Available levels: DEBUG, INFO, WARNING, ERROR, CRITICAL
yt --log-level INFO --verbose projects list

Log Level Details

DEBUG: Detailed information, typically only useful for diagnosing problems
INFO: General information about what the program is doing
WARNING: Something unexpected happened, but the software is still working
ERROR: A serious problem occurred, the software was unable to perform a function
CRITICAL: A very serious error occurred, the program may be unable to continue

Log Files

By default, logs are written to both console and file for comprehensive debugging support.

Default Locations

Linux/macOS: ~/.local/share/youtrack-cli/youtrack-cli.log
Windows: %LOCALAPPDATA%\\youtrack-cli\\youtrack-cli.log
Custom location: Set XDG_DATA_HOME environment variable

File Management Options

# Disable file logging (console only)
yt --no-log-file issues list

# View current log file location
yt config get log-file-path

Log File Features

Automatic rotation: Logs rotate when they reach 10MB
Backup retention: Keeps 5 backup files (50MB total)
Structured format: JSON-like structured data with timestamps
Cross-session persistence: Logs persist across CLI sessions

Sensitive Data Protection

The logging system automatically masks sensitive information to protect security:

Automatic Masking

The following patterns are automatically masked in all logs:

API tokens: token=***MASKED***
Passwords: password=***MASKED***
API keys: api_key=***MASKED***
Authorization headers: Authorization: Bearer ***MASKED***
Bearer tokens in URLs

Example Protected Output

Original: "Making request to https://youtrack.example.com/api?token=abc123xyz"
Logged:   "Making request to https://youtrack.example.com/api?token=***MASKED***"

Debugging Common Issues

API Connectivity Problems

# Enable debug logging for detailed API calls
yt --debug auth login

# Monitor all API requests and responses
yt --debug --log-level DEBUG issues list

# Focus only on errors
yt --log-level ERROR issues list

Authentication Issues

# Debug authentication flow
yt --debug auth login

# Verify token validity with verbose output
yt --verbose auth token --show

Performance Issues

# Monitor API response times
yt --debug --log-level DEBUG issues list

# Track slow operations
yt --debug time log ISSUE-123 "2h"

Network Connectivity

# Debug network issues with full detail
yt --debug --log-level DEBUG projects list

# Monitor retry attempts
yt --verbose issues list

Log Output Examples

Console Output

With --verbose flag:

[10:30:15] INFO     Starting operation                operation=list_issues project=TEST
[10:30:15] INFO     API call completed               method=GET status_code=200 duration_ms=245.5

With --debug flag:

[10:30:15] DEBUG    Making API request               method=GET url=https://youtrack.example.com/api/issues attempt=1
[10:30:15] DEBUG    API call completed               method=GET status_code=200 duration_ms=245.5
[10:30:15] DEBUG    Request successful               status_code=200

File Output

Log files contain structured JSON-like entries:

2024-07-05 10:30:15 - youtrack_cli.api - DEBUG - API call completed {
  "method": "GET",
  "url": "https://youtrack.example.com/api/issues?token=***MASKED***",
  "status_code": 200,
  "duration_ms": 245.5,
  "attempt": 1
}

Error Logging

Errors include contextual information:

2024-07-05 10:30:15 - youtrack_cli.operations - ERROR - YouTrack operation failed {
  "operation": "create_issue",
  "error_type": "AuthenticationError",
  "message": "Invalid credentials or token expired",
  "url": "https://youtrack.example.com/api/issues"
}

Structured Logging for Developers

The CLI uses structured logging throughout for better debugging and monitoring.

Operation Tracking

High-level operations are logged with context:

from youtrack_cli.logging import log_operation

log_operation("create_issue", project="TEST", issue_type="Bug", user="john.doe")

API Call Tracking

All API calls are automatically logged with performance metrics:

from youtrack_cli.logging import log_api_call

log_api_call(
    method="POST",
    url="https://youtrack.example.com/api/issues",
    status_code=201,
    duration=0.5,
    issue_id="TEST-123"
)

Custom Logger Usage

For custom logging in extensions or plugins:

from youtrack_cli.logging import get_logger

logger = get_logger("my_extension")
logger.info("Extension operation", action="process_data", count=42)

Configuration

Environment Variables

XDG_DATA_HOME: Override default log file location
YT_LOG_LEVEL: Set default log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
YT_NO_LOG_FILE: Disable file logging (set to “1” or “true”)

Log Rotation Settings

Current settings (not user-configurable):

Maximum file size: 10MB per log file
Backup count: 5 files retained
Total disk usage: ~50MB maximum
Rotation behavior: Automatic when size limit reached

Performance Considerations

File logging impact: Minimal performance overhead
Debug logging: May slow operations by 10-20% due to detailed output
Console logging: Rich formatting has minimal impact
Log rotation: Happens automatically in background

Best Practices

Development and Testing

# Use debug mode during development
yt --debug config set default-project TEST

# Monitor API calls for new integrations
yt --log-level DEBUG --verbose issues create "Test Issue"

Production Usage

# Use warning level for automated scripts
yt --log-level WARNING issues list --format json > issues.json

# Enable info level for monitoring
yt --log-level INFO time report --format json

Troubleshooting Steps

Start with verbose mode: yt --verbose <command>
Enable debug for API issues: yt --debug <command>
Check log files: Review ~/.local/share/youtrack-cli/youtrack-cli.log
Focus on errors: yt --log-level ERROR <command>
Report issues: Include relevant log excerpts when reporting bugs

Integration with External Tools

Log Aggregation

The structured JSON format makes logs suitable for aggregation tools:

ELK Stack: Parse JSON logs with Logstash
Fluentd: Direct JSON ingestion
Splunk: Index structured log data
Datadog: Log forwarding and analysis

Monitoring and Alerting

Set up alerts based on log patterns:

Error rates: Monitor ERROR and CRITICAL level messages
API performance: Track duration_ms fields
Authentication failures: Alert on AuthenticationError events
Rate limiting: Monitor RateLimitError occurrences