Skip to main content

​
Overview

TikTokLive includes a built-in logging system that helps you debug connection issues, track events, and monitor your client’s behavior. The library uses Python’s standard logging module with a custom handler.

​
Quick Start

Enable debug logging to see detailed information about your client: 
from TikTokLive import TikTokLiveClient
from TikTokLive.client.logger import LogLevel

client = TikTokLiveClient(
    unique_id="@username",
    debug=True  # Enable debug mode
)
This will automatically set the log level to DEBUG and output logs to stderr.

​
Log Levels

TikTokLive supports all standard Python logging levels through the LogLevel enum: 
from TikTokLive.client.logger import LogLevel

# Available log levels
LogLevel.CRITICAL  # 50 - Critical errors only
LogLevel.ERROR     # 40 - Errors and above
LogLevel.WARNING   # 30 - Warnings and above (default)
LogLevel.INFO      # 20 - Info and above
LogLevel.DEBUG     # 10 - Debug and above (most verbose)
LogLevel.NOTSET    # 0  - All messages

​
Custom Logger Configuration

You can configure the logger manually for more control: 
import sys
from TikTokLive.client.logger import TikTokLiveLogHandler, LogLevel

# Get or create the logger
logger = TikTokLiveLogHandler.get_logger(
    level=LogLevel.DEBUG,
    stream=sys.stdout  # Output to stdout instead of stderr
)

# The logger is now configured
logger.info("Logger is ready")
logger.debug("Debug information")
logger.warning("Warning message")
logger.error("Error occurred")

​
Logger Output Format

The TikTokLive logger uses a custom format inspired by SpringBoot: 
[TikTokLive] INFO from c.w.routes.fetch_room_info:42 — Fetching room info
[TikTokLive] DEBUG from c.w.web_client:156 — Request completed
[TikTokLive] ERROR from c.client:89 — Connection failed
Format breakdown:
  • [TikTokLive] - Logger name
  • INFO/DEBUG/ERROR - Log level
  • c.w.routes.fetch_room_info - Compressed file path
  • 42 - Line number
  • Message content

​
Using Debug Mode

​
Basic Debug Mode

Enable debug mode when creating your client: 
from TikTokLive import TikTokLiveClient

client = TikTokLiveClient(
    unique_id="@username",
    debug=True
)

if __name__ == '__main__':
    client.run()

​
Debug Mode with Custom Level

Set a specific log level even with debug mode: 
from TikTokLive import TikTokLiveClient
from TikTokLive.client.logger import TikTokLiveLogHandler, LogLevel

# Configure logger before creating client
logger = TikTokLiveLogHandler.get_logger(level=LogLevel.INFO)

client = TikTokLiveClient(unique_id="@username")

​
Advanced Logger Configuration

​
Custom Stream Output

Redirect logs to a file: 
import sys
from TikTokLive.client.logger import TikTokLiveLogHandler, LogLevel

# Write logs to a file
with open('tiktok_live.log', 'w') as log_file:
    logger = TikTokLiveLogHandler.get_logger(
        level=LogLevel.DEBUG,
        stream=log_file
    )
    
    # Your client code here
    client = TikTokLiveClient(unique_id="@username")
    client.run()

​
Custom Formatter

Create a logger with a custom formatter: 
import logging
import sys
from TikTokLive.client.logger import TikTokLiveLogHandler, LogLevel

# Create custom formatter
custom_format = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
custom_formatter = logging.Formatter(custom_format, "%Y-%m-%d %H:%M:%S")

# Create logger handler
handler = TikTokLiveLogHandler(stream=sys.stdout, formatter=custom_formatter)

# Get logger and configure
logger = logging.getLogger("TikTokLive")
logger.addHandler(handler)
logger.setLevel(LogLevel.DEBUG.value)

​
Logging in Event Handlers

Use the logger within your event handlers for consistent logging: 
import logging
from TikTokLive import TikTokLiveClient
from TikTokLive.events import ConnectEvent, CommentEvent
from TikTokLive.client.logger import TikTokLiveLogHandler, LogLevel

# Get the logger
logger = TikTokLiveLogHandler.get_logger(level=LogLevel.DEBUG)

client = TikTokLiveClient(unique_id="@username")

@client.on(ConnectEvent)
async def on_connect(event: ConnectEvent):
    logger.info(f"Connected to @{event.unique_id}")
    logger.debug(f"Room ID: {event.room_id}")

@client.on(CommentEvent)
async def on_comment(event: CommentEvent):
    logger.debug(f"Comment from {event.user.nickname}: {event.comment}")

if __name__ == '__main__':
    client.run()

​
Debugging Connection Issues

When troubleshooting connection problems, enable debug logging: 
from TikTokLive import TikTokLiveClient
from TikTokLive.client.logger import TikTokLiveLogHandler, LogLevel
from TikTokLive.client.errors import TikTokLiveError
import traceback

# Enable detailed logging
logger = TikTokLiveLogHandler.get_logger(level=LogLevel.DEBUG)

client = TikTokLiveClient(
    unique_id="@username",
    debug=True
)

try:
    client.run()
except TikTokLiveError as e:
    logger.error(f"TikTokLive error: {e}")
    logger.error(traceback.format_exc())
except Exception as e:
    logger.critical(f"Unexpected error: {e}")
    logger.critical(traceback.format_exc())

​
Logger Path Formatting

The TikTokLiveLogHandler automatically compresses file paths for cleaner output: 
# Full path: /path/to/project/TikTokLive/client/web/routes/fetch_room_info.py
# Compressed: c.w.routes.fetch_room_info.py
This is done using the format_path method: 
from TikTokLive.client.logger import TikTokLiveLogHandler
import logging

# Access the formatter
record = logging.LogRecord(
    name="TikTokLive",
    level=logging.INFO,
    pathname="/home/user/project/TikTokLive/client/client.py",
    lineno=42,
    msg="Test message",
    args=(),
    exc_info=None
)

formatted_path = TikTokLiveLogHandler.format_path(record)
print(formatted_path)  # "c.client.py"

​
Complete Logging Example

import sys
import logging
from TikTokLive import TikTokLiveClient
from TikTokLive.client.logger import TikTokLiveLogHandler, LogLevel
from TikTokLive.events import ConnectEvent, DisconnectEvent, CommentEvent
from TikTokLive.client.errors import TikTokLiveError

# Configure logging
logger = TikTokLiveLogHandler.get_logger(
    level=LogLevel.DEBUG,
    stream=sys.stdout
)

client = TikTokLiveClient(unique_id="@username")

@client.on(ConnectEvent)
async def on_connect(event: ConnectEvent):
    logger.info(f"✓ Successfully connected to @{event.unique_id}")
    logger.debug(f"Room ID: {event.room_id}")

@client.on(DisconnectEvent)
async def on_disconnect(event: DisconnectEvent):
    logger.warning("Disconnected from stream")

@client.on(CommentEvent)
async def on_comment(event: CommentEvent):
    logger.debug(f"{event.user.nickname}: {event.comment}")

if __name__ == '__main__':
    try:
        logger.info("Starting TikTokLive client...")
        client.run()
    except TikTokLiveError as e:
        logger.error(f"Client error: {e}")
    except KeyboardInterrupt:
        logger.info("Client stopped by user")
    except Exception as e:
        logger.critical(f"Unexpected error: {e}")

​
Best Practices

Use Debug Mode

Always enable debug mode during development to catch issues early.

Production Logging

Use WARNING or ERROR level in production to avoid log spam.

Log Files

Write logs to files in production for later analysis and debugging.

Structured Logging

Include context in log messages (username, room_id, etc.) for easier debugging.
The logger singleton is created once and reused. Calling get_logger() multiple times returns the same instance unless you explicitly pass a new level parameter.

Build docs developers (and LLMs) love

Get started for freeTalk to us