diff --git a/changelog.d/+support-logging-to-json.added.md b/changelog.d/+support-logging-to-json.added.md new file mode 100644 index 000000000..f9427181f --- /dev/null +++ b/changelog.d/+support-logging-to-json.added.md @@ -0,0 +1,2 @@ +Document how to log with structured (JSON) logs and add an optional dependency +to accomplish this. diff --git a/docs/production.rst b/docs/production.rst index 8fc5bc10a..c647e75d7 100644 --- a/docs/production.rst +++ b/docs/production.rst @@ -6,3 +6,4 @@ Running in production .. toctree:: production/task-queue + production/logging diff --git a/docs/production/logging.rst b/docs/production/logging.rst new file mode 100644 index 000000000..9cd2f1b4b --- /dev/null +++ b/docs/production/logging.rst @@ -0,0 +1,39 @@ +===================== +Logging in production +===================== + +Structured logging with JSON +============================ + +For log analysis it is frequently useful to have the logs in a structured +format. + +By installing ``python-json-logger`` (for instance via ``pip install +python-json-logger`` or ``pip install ".[jsonlogging]"``) and setting up +a logging formatter like this: + +:: + + "formatters": { + .. + "json": { + "()": "pythonjsonlogger.json.JsonFormatter", + "format": "asctime,levelname,name,message", + "style": ",", + }, + .. + }, + "handlers": { + "json": { + "class": "logging.StreamHandler", + "formatter": "json", + }, + }, + +... the logs produced by argus will be in JSON format. + +See `Python logging LogRecord attributes +`_ for +other default keywords useful to put in the "format"-line. "message" is +a human-chosen plaintext explicitly written in the code and should always be +included. diff --git a/pyproject.toml b/pyproject.toml index 12643f7df..6fb442985 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -74,6 +74,7 @@ dev = [ "tox>=4", "build", # for debugging builds/installs ] +jsonlogging = ["python-json-logger"] [tool.hatch.version] source = "versioningit"