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 above INFO hides what ContextGem reports at that level, e.g. the retries and the fallback models that it tries. ERROR and above, or OFF, also hide the warnings on what happens while it runs, e.g. an extraction that fails when raise_exception_on_extraction_error=False is passed. The default INFO level shows these 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, a request that a model or its provider refuses to answer, or the answers that a decision model refuses to give in aspect extraction. 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. The warning on a model whose costs cannot be calculated has a category of its own, UnknownPricesWarning, a subclass of ContextGemWarning (see 🛑 Stopping a Model Whose Prices Are Unknown).

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 writes its log to standard output (sys.stdout) with a handler of its own, and its logger does not pass the messages on to the root logger: a handler of your application, e.g. one that sends your logs to a log collector, does not get them, unless you add it to the contextgem logger (logging.getLogger("contextgem").addHandler(...)), where it stays when the settings are changed. With OFF, it gets no messages, until the level is changed again.

The errors that ContextGem logs on an answer of a model that cannot be used say where and how the answer is invalid, without its values, which can hold text of your documents. litellm logs with loggers of its own: if your application logs them at the DEBUG level, they log each request that litellm sends, its prompt included.

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

The timestamp and the level are in color where the log is written to a terminal. Written elsewhere, e.g. to a file or to the log of a CI job, the log has no color codes, unless the FORCE_COLOR environment variable is set, e.g. for a CI service that shows colors. With NO_COLOR set, the log has no colors at all (see no-color.org). In a Jupyter notebook, whose output is not a terminal, set FORCE_COLOR=1 to see the colors.