Environment Variables
The SDK reads the variables on this page at run time. Each one sets something an application can also set in code, and is meant for the case where the code is not yours to change, or not worth changing to investigate a problem.
Logging
The logging variables are read once, when the SDK is first imported, so they have to be set before the
process starts. Setting them in os.environ after import couchbase has no effect.
They configure two things together: the native core’s log, and the SDK’s Python loggers under
couchbase. An application that would rather send the native core’s log through its own Python
logging calls couchbase.configure_logging() instead. The two cannot be combined:
configure_logging() raises RuntimeError when PYCBC_LOG_LEVEL is set.
- PYCBC_LOG_LEVEL
Turns logging on, at the given level:
trace,debug,info,warning,error,criticaloroff.warnis accepted aswarning, and the value is not case sensitive. An unrecognized value logs a warning and usesinfo.Unset or empty, the native core does not log, the SDK’s Python loggers are left to the application’s logging configuration, and the other logging variables are ignored.
Without
PYCBC_LOG_FILE, the native core logs to standard error. ThecouchbasePython logger gets the same level. If the application has already configured a handler that would receive its records, on thecouchbaselogger or the root logger, the SDK leaves them to it; otherwise it adds a console handler of its own. The root logger is never changed.$ PYCBC_LOG_LEVEL=debug python my_app.py
- PYCBC_LOG_FILE
Writes the log to files named from this path instead of to the console. Read only when
PYCBC_LOG_LEVELis set.The native core writes
<path>.000000.txtand starts the next numbered file when the current one passes 100 MiB. A restarted process appends to the highest-numbered file, and older files are never deleted, so attraceanddebugthey need cleaning up. The SDK’s Python records go to the path exactly as given.$ PYCBC_LOG_LEVEL=debug PYCBC_LOG_FILE=/var/log/couchbase-sdk.log python my_app.py
- PYCBC_ENABLE_CONSOLE
Logs to the console as well as to
PYCBC_LOG_FILE.1,true,yesandonturn it on, ignoring case; any other value, or none, leaves it off. Without a log file the console is always on, so this changes nothing.
- COUCHBASE_CXX_CLIENT_MAXIMIZE_LOGGER_CYCLE_SIZE
Raises the size at which the native core starts its next log file from 100 MiB to 1 GiB. Any non-empty value turns it on. It matters only with
PYCBC_LOG_FILE, for a long capture attracethat would otherwise be spread over many files. The variable belongs to the native core, which is shared with other Couchbase SDKs, hence the name.
Option validation
- PYCBC_OPTION_VALIDATION
What the SDK does when an operation is given an option key that its options class does not carry, or one the protocol in use cannot act on:
ignore,warnorstrict. The default iswarn.warnemitsCouchbaseOptionWarningfor an unknown key, naming the closest known key where there is one, andCouchbaseApplicabilityWarningfor a key that changes nothing.strictraisesInvalidArgumentExceptioninstead.ignoresays nothing.The variable is the default for every cluster in the process. A cluster given
option_validationinClusterOptionsuses that instead, for its own options and every operation under it. A cluster given none reads the variable at each operation, so changing it inos.environtakes effect on the next one.A value that is none of the three is reported with a
CouchbaseOptionWarningand treated aswarn. It never raises, since the operation it is read for may come hours into a run.$ PYCBC_OPTION_VALIDATION=strict python -m pytest
Windows
- PYCBC_OPENSSL_DIR
The directory holding the OpenSSL libraries,
libsslandlibcrypto, that the SDK’s native extension loads. Read only on Windows, and only when the extension fails to load at import; the SDK then registers this directory with the DLL search path and tries once more. Unset, it uses the interpreter’s ownDLLsdirectory, which ships both libraries.The released wheels link their TLS library statically and never need it. It is for an SDK built from source against a separately installed OpenSSL, and the build reads the same variable, as the OpenSSL root directory to build against.