Support for custom fields in juturna logging

[b3by]

Description

This PR introduces a number of changes to the logging facility in juturna.

1. Add formatters to the juturna logger

Users can now add custom formatters without the need to create a handler. The formatter will be added to the current handler.

import logging

import juturna as jt


user_fmt = logging.Formatter('%(asctime)s --> %(message)s')

jt.log.add_formatter('custom', user_fmt)
jt.log.formatter('custom')

2026-06-16 17:20:59,360 --> node created!
2026-06-16 17:20:59,361 --> warmed up node source_1
2026-06-16 17:20:59,361 --> warmed up node sink_1
2026-06-16 17:20:59,361 --> pipe warmed up!
2026-06-16 17:20:59,369 --> node created!
2026-06-16 17:20:59,371 --> warmed up node source_1
2026-06-16 17:20:59,371 --> warmed up node sink_1
2026-06-16 17:20:59,372 --> pipe warmed up!
2026-06-16 17:21:00,372 --> this is what?
2026-06-16 17:21:00,372 --> and this?

2. New juturna formatter

A new type of formatter was added to juturna, called JuturnaFormatter. In combination with a new filter called JuturnaPipelineFilter, this allows to add custom fields to the log records directly in the pipeline configuration file.

The juturna formatter can be used like any other formatter:

import juturna as jt


usr_fmt = jt.log.JuturnaFormatter('%(asctime)s | %(message)s')

jt.log.add_formatter('custom', user_fmt)
jt.log.formatter('custom')

A juturna formatter accepts non-standard fields. If those fields are not available, their name will be printed in the log output:

usr_fmt = jt.log.JuturnaFormatter('%(asctime)s | %(custom_field)6s | %(name)s | %(message)s')

Custom fields can be defined on a pipeline level, directly in the configuration file:

"pipeline": {
  "name": "awesome_pipe",
  "id": "123456",
  "folder": "./",
  "log_extra": {
    "custom_field": "AWSM"
  }
}

2026-06-16 17:32:19,012 |   AWSM | jt.pipe_0.source_1 | node created!
2026-06-16 17:32:19,014 |   AWSM | jt.pipe_0 | warmed up node source_1
2026-06-16 17:32:19,014 |   AWSM | jt.pipe_0 | warmed up node sink_1
2026-06-16 17:32:19,015 |   AWSM | jt.pipe_0 | pipe warmed up!

3. Log configuration file for juturna service

The juturna service CLI was changed so that, instead of individual parameters for the logger, it now accepts a fully fledged log configuration file. This allows to achieve the very same granularity offered by the low-level logging APIs in juturna.

(.venv) $ python -m juturna serve -H 0.0.0.0 -p 8888 -f run -l log_config.json

An example of configuration file for the logs follows:

{
  "version": 1,
  "disable_existing_loggers": true,
  "formatters": {
    "standard": {
      "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
    },
    "json": {
      "()": "juturna.utils.log_utils.JsonFormatter"
    },
    "juturna": {
      "format": "%(env)s | %(name)s | %(message)s",
      "()": "juturna.utils.log_utils.JuturnaFormatter"
    }
  },
  "handlers": {
    "console": {
      "class": "logging.StreamHandler",
      "level": "DEBUG",
      "formatter": "juturna",
      "stream": "ext://sys.stdout",
      "filters": [
        "custom"
      ]
    },
    "file_stream": {
      "class": "logging.handlers.RotatingFileHandler",
      "level": "DEBUG",
      "formatter": "json",
      "filename": "/tmp/juturna_log.json",
      "maxBytes": 10485760,
      "backupCount": 20,
      "encoding": "utf8"
    },
    "service": {
      "class": "logging.StreamHandler",
      "level": "DEBUG",
      "formatter": "standard",
      "stream": "ext://sys.stdout"
    }
  },
  "filters": {
    "custom": {
      "()": "juturna.utils.log_utils.JuturnaPipelineFilter"
    }
  },
  "root": {
    "level": "NOTSET",
    "handlers": [
      "console"
    ],
    "propogate": "yes"
  },
  "loggers": {
    "jt": {
      "handlers": [
        "console",
        "file_stream"
      ]
    },
    "jt.service": {
      "handlers": ["service"]
    }
  }
}

4. jt.utils.log_utils now exposes formatters and filters

The jt.log module now exposes some formatters and filters that are shipped with juturna, so that their classes can be linked in the log configuration files. These are:

• juturna.utils.log_utils.ColoredFormatter
• juturna.utils.log_utils.JsonFormatter
• juturna.utils.log_utils.JuturnaFormatter
• juturna.utils.log_utils.JuturnaPipelineFilter

PR type
Select all the labels that apply to this PR.

• New feature (non-breaking change which adds functionality)
• Code refactoring

[GaijinKa]

The PR looks good to me.

I've only raised a couple of concerns about _REGISTRY and a convention lock-in that could become problematic if it remains undocumented and we later decide to change that convention. No changes requested, just a comment

[GaijinKa]

You can merge this PR!

As a side note, I think this PR should be flagged as breaking, since the CLI parameters have changed. However, we already have several breaking changes in the stack for the next release, so the version will be bumped anyway without amend any commit