Skip to content

# Job Logging

Nautobot Jobs support rich, structured logging using `self.logger`, with logs surfaced in both the UI and API. This guide covers logging best practices, structured metadata, and important version notes.

## Logging Patterns

Changed in version 2.0.0

Nautobot logs messages from Jobs in a structured way, storing them as part of the `JobResult` and displaying them in the UI. This enables Jobs to provide real-time feedback, track their progress, and surface success or failure messages clearly to the user.

Use the `self.logger` property to write log messages from within your Job code. These logs appear in the UI and are also saved as `JobLogEntry` records associated with the current `JobResult`.

## Logging Levels

Nautobot supports standard logging levels, with additional custom levels for success and failure messages:

Level | Method | Description
--- | --- | ---
DEBUG | `self.logger.debug()` | Detailed diagnostic information.
INFO | `self.logger.info()` | General operational messages.
SUCCESS | `self.logger.success()` | Indicates successful operations.
WARNING | `self.logger.warning()` | Signals potential issues.
FAILURE | `self.logger.failure()` | Denotes failed operations.
ERROR | `self.logger.error()` | Serious errors that prevent execution.
CRITICAL | `self.logger.critical()` | Critical conditions.

Note

`logger.success()` and `logger.failure()` were introduced in versions 2.4.0 and 2.4.5, respectively.

## Writing Log Messages

Example

    self.logger.info("Job is starting.")
    self.logger.error("An unexpected error occurred.")
    self.logger.success("Provisioning complete.")

For most use cases, you'll use `self.logger`. You can also obtain the same logger via `nautobot.extras.jobs.get_task_logger(__name__)`, though this is less common.

## Structured Log Context with `extra`

You can attach structured metadata to log messages using the `extra` parameter. This enables grouping and improves how logs are displayed or queried:

- `grouping`: A logical label used to associate related log messages. It is useful for filtering, context, and organizing output in the API or database
- `object`: A Nautobot object instance to associate with this log message (e.g., a Device)
- `skip_db_logging`: Set to `True` to avoid saving the log message in the database (it will still be visible in the Celery worker log output)

Example

    self.logger.info(
        "Validated device",
        extra={
            "grouping": "inventory-check",
            "object": device
        }
    )

To skip writing a log entry to the database but still print it to the console of the Celery worker:

Example

    self.logger.info("Debugging message", extra={"skip_db_logging": True})

If `grouping` is not specified, Nautobot uses the current function name as a default. If `object` is omitted, the log is not associated with any model instance.

Example

    from nautobot.apps.jobs import Job

    class MyJob(Job):
        def run(self):
            self.logger.info("This job is running!", extra={"grouping": "myjobisrunning", "object": self.job_result})

## Log Message Formatting

Log messages can include Markdown formatting, and a limited subset of HTML is also supported for added emphasis in the UI.

## Sanitizing Log Messages

As a security precaution, Nautobot passes all log messages through `nautobot.core.utils.logging.sanitize()` to remove sensitive information like passwords or tokens. You should still avoid logging such values yourself, as this redaction is best-effort. The sanitization behavior can be customized using `settings.SANITIZER_PATTERNS`.

Changed in version 2.0.0 — Significant API changes

The Job class logging functions (example: `self.log(message)`, `self.log_success(obj=None, message=message)`, etc) have been removed. Also, the convenience method to mark a Job as failed, `log_failure()`, has been removed. To replace the functionality of this method, you can log an error message with `self.logger.error()` and then raise an exception to fail the Job. Note that it is no longer possible to manually set the Job Result status as failed without raising an exception in the Job.

Changed in version 2.0.0

The `AbortTransaction` class was moved from the `nautobot.utilities.exceptions` module to `nautobot.core.exceptions`. Jobs should generally import it from `nautobot.apps.exceptions` if needed.

Added in version 2.4.0 — `logger.success()` added

You can now use `self.logger.success()` to log a message at the level `SUCCESS`, which is located between the standard `INFO` and `WARNING` log levels.

Added in version 2.4.5 — `logger.failure()` added

You can now use `self.logger.failure()` to log a message at the level `FAILURE`, which is located between the standard `WARNING` and `ERROR` log levels.