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 messagesDEBUG- Shows debug information and aboveINFO- Shows informational messages and above (default)SUCCESS- Shows success messages and aboveWARNING- Shows warnings and errors onlyERROR- Shows errors and critical messages onlyCRITICAL- Shows only critical messagesOFF- Completely disables logging
Default:
INFO- CONTEXTGEM_SUPPRESS_LITELLM_NOISE
ContextGem hides the non-actionable log messages of
litellm, at any logging level, includingOFF. Set the variable to0to 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:
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
WARNINGlevel or above: e.g. an extraction that fails whenraise_exception_on_extraction_error=Falseis 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, andCONTEXTGEM_LOGGER_LEVELcontrols these messages as any other.What in your code will not have the expected effect is issued as a Python warning of the
ContextGemWarningcategory, a subclass ofUserWarning: 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 ofContextGemWarning(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.