Logging Configuration

Logging Configuration#

ContextGem provides comprehensive logging to help you monitor and debug the extraction process. You can control logging behavior using environment variables. ContextGem uses a namespaced logger under the name contextgem.

⚙️ Environment Variables#

ContextGem uses the following environment variables for logging configuration:

CONTEXTGEM_LOGGER_LEVEL

Sets the logging level. Valid values are:

  • TRACE - Most verbose, shows all log messages

  • DEBUG - Shows debug information and above

  • INFO - Shows informational messages and above (default)

  • SUCCESS - Shows success messages and above

  • WARNING - Shows warnings and errors only

  • ERROR - Shows errors and critical messages only

  • CRITICAL - Shows only critical messages

  • OFF - Completely disables logging

Default: INFO

CONTEXTGEM_SUPPRESS_LITELLM_NOISE

ContextGem hides the non-actionable log messages of litellm, at any logging level, including OFF. Set the variable to 0 to show these messages. With any other value, they stay hidden.

Default: 1

Warning

Not recommended: Setting the level to OFF or above INFO (such as WARNING or ERROR) may cause you to miss helpful messages, guidance, recommendations, and important information about the extraction process. The default INFO level provides a good balance of useful information without being too verbose.

🔧 Setting Environment Variables#

Before importing ContextGem:

# Set logging level to WARNING
export CONTEXTGEM_LOGGER_LEVEL=WARNING

# Disable logging completely
export CONTEXTGEM_LOGGER_LEVEL=OFF

In Python before import:

import os

# Set logging level to DEBUG
os.environ["CONTEXTGEM_LOGGER_LEVEL"] = "DEBUG"

# Import ContextGem after setting environment variables
import contextgem

🔄 Changing Settings at Runtime#

If you need to change logging settings after importing ContextGem, set the environment variables and call the reload_logger_settings() function, which applies both of them:

Changing logger settings at runtime#
import os

from contextgem import reload_logger_settings


# Initial logger settings are loaded from environment variables at import time

# Change logger level to WARNING
os.environ["CONTEXTGEM_LOGGER_LEVEL"] = "WARNING"
print("Setting logger level to WARNING")
reload_logger_settings()
# Now the logger will only show WARNING level and above messages

# Disable the logger completely
os.environ["CONTEXTGEM_LOGGER_LEVEL"] = "OFF"
print("Disabling the logger")
reload_logger_settings()
# Now the logger is disabled and won't show any messages

# You can re-enable the logger by setting it back to a valid level
# os.environ["CONTEXTGEM_LOGGER_LEVEL"] = "INFO"
# reload_logger_settings()

⚠️ Warnings#

ContextGem reports what needs your attention in one of two ways, by what it is about:

  • What happens while ContextGem runs is logged, at the WARNING level or above: e.g. an extraction that fails when raise_exception_on_extraction_error=False is passed to the extraction method, a chat response cut off at the max output tokens, or the answers that a decision model refuses to give. Each occurrence is logged, and CONTEXTGEM_LOGGER_LEVEL controls these messages as any other.

  • What in your code will not have the expected effect is issued as a Python warning of the ContextGemWarning category, a subclass of UserWarning: e.g. tools set on an LLM that is used for extraction, or an output language set together with a custom system message. Such a warning points to the line of your code that caused it, e.g. the line that creates the model, and Python shows it once for that line.

Python warnings are not log messages: CONTEXTGEM_LOGGER_LEVEL does not affect them, and they are shown also with OFF. Filter them with the standard warnings module, by their category, as a filter by the module of ContextGem does not match a warning that points to your code. In your tests, you can make them errors, to catch such code before it runs in production.

import warnings

from contextgem import ContextGemWarning

# Hide all the warnings of ContextGem
warnings.filterwarnings("ignore", category=ContextGemWarning)

# Or only some of them, by the start of the message
warnings.filterwarnings(
    "ignore",
    message="`output_language` applies to the extraction prompts only",
    category=ContextGemWarning,
)

# Or make them errors, e.g. in your tests
warnings.filterwarnings("error", category=ContextGemWarning)

📋 Log Format#

ContextGem logs use the following format:

[contextgem] 2025-01-11 15:30:45.123 | INFO    | Your log message here

Each log entry includes:

  • Timestamp (with milliseconds)

  • Log level

  • Log message