> ## Documentation Index
> Fetch the complete documentation index at: https://docs.westyx.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK - Logging

> The westyx_nexus logger, the startup summary, and custom NexusLogger sinks.

By default the SDK logs through Python's standard `logging` module, to the logger named
**`westyx_nexus`**, which carries only a `NullHandler`. That is what the
[Logging HOWTO](https://docs.python.org/3/howto/logging.html#configuring-logging-for-a-library)
asks of a library: silent until the application configures logging, visible as soon as it does,
with nothing passed to the SDK.

```python theme={null}
import logging

logging.basicConfig(level=logging.INFO)                       # the SDK's INFO and above appear
logging.getLogger("westyx_nexus").setLevel(logging.DEBUG)     # every sync, every stream event
```

The name is exported as `LOGGER_NAME`.

## What the SDK logs

| Level | When |
| - | - |
| `debug` | Every sync (success or 304), every stream event |
| `info` | Client ready, the [startup summary](#the-startup-summary), stream connected, fallback to polling, a WIF session refreshed |
| `warning` | A resource the server [did not deliver](#resources-the-server-did-not-deliver), the environment switched off, a WIF refresh that failed while the session was still valid |
| `error` | A background sync that failed, a stream transport error, an observer callback that raised |

```
nexus: client ready (key_type=sk, kind='backend', wif=off, ttl=60.0s)
nexus: client loaded configs=[database.url, max.items] secrets=[DB_PASSWORD] flags=[new.checkout]
nexus: sync OK - configs=12 secrets=4 flags=7 key_type=sk kind='backend'
nexus: SSE stream connected
nexus: SSE event=flag.toggled - triggering sync
nexus: sync 304 Not Modified - cache retained
```

## The startup summary

After the first sync both clients log one `info` record naming what they received:

```
nexus: client loaded configs=[database.url, max.items] secrets=[DB_PASSWORD] flags=[new.checkout]
```

Names only, never a value. Each list is sorted and capped at 50 names, with a `+N more` entry after
that, so a large service stays one readable line. It is how you confirm from a pod's log which
configs, secrets and flags a deployment actually pulled.

| Setup | The summary |
| - | - |
| Django, Flask or FastAPI adapter | Through the `westyx_nexus` logger, so it shows wherever your logging configuration sends `INFO` |
| Your own `logger=` | Through it, at `info` |
| No `logger=` | Through the `westyx_nexus` logger; and with `WESTYX_NEXUS_LOG_STARTUP=1` in the environment, also written to standard error as one line - for a pod whose application never configured logging |

```
westyx-nexus: client loaded configs=[database.url, max.items] secrets=[DB_PASSWORD] flags=[new.checkout]
```

## Resources the server did not deliver

A sync can report resources it left out - a secret that has no value yet (`secret_not_set`), a
config whose `{{secret:KEY}}` reference does not resolve (`config_unresolved_secret`). Such a secret
or config reads as absent. Each omission is logged as a `warning` the first time it appears;
`client.sync_errors` lists the current ones. `log_sync_errors=False` keeps the list without the log
lines.

```
nexus: the server did not deliver a resource - code=secret_not_set resource_type=secret key=API_TOKEN detail=...
```

## Secret values never reach the logger

No log record carries a secret's value, the API key or a session token. This is enforced: a test
drives a sync, a write and the WIF path through a capturing logger and fails if any of them appears.
Key names do appear - in the startup summary and in the omission warning. A name identifies what to
look up; it is not the credential.

## A custom logger

`NexusConfig.logger` takes any object with these methods - a `Protocol`, so there is no base class
to inherit:

```python theme={null}
from typing import Protocol

class NexusLogger(Protocol):
    def debug(self, message: str) -> None: ...
    def info(self, message: str) -> None: ...
    def warning(self, message: str) -> None: ...
    def error(self, message: str, cause: BaseException | None = None) -> None: ...
```

A logger written without `warning` still works: its warnings arrive at `info`.

`StdlibNexusLogger(name="myapp.nexus")` nests the SDK under your own logger hierarchy.

### structlog

```python theme={null}
import structlog
from westyx_nexus import NexusConfig

class StructlogAdapter:
    def __init__(self, log: structlog.BoundLogger) -> None:
        self._log = log

    def debug(self, message: str) -> None:
        self._log.debug(message)

    def info(self, message: str) -> None:
        self._log.info(message)

    def warning(self, message: str) -> None:
        self._log.warning(message)

    def error(self, message: str, cause: BaseException | None = None) -> None:
        if cause is not None:
            self._log.error(message, exc_info=cause)
        else:
            self._log.error(message)

config = NexusConfig(base_url="...", api_key="...", logger=StructlogAdapter(structlog.get_logger("nexus")))
```

### Loguru

```python theme={null}
from loguru import logger

class LoguruAdapter:
    def debug(self, msg: str) -> None:
        logger.bind(component="nexus").debug(msg)

    def info(self, msg: str) -> None:
        logger.bind(component="nexus").info(msg)

    def warning(self, msg: str) -> None:
        logger.bind(component="nexus").warning(msg)

    def error(self, msg: str, cause: BaseException | None = None) -> None:
        if cause is not None:
            logger.bind(component="nexus").opt(exception=cause).error(msg)
        else:
            logger.bind(component="nexus").error(msg)
```

## A logger that raises is contained

A logger whose method raises never fails an SDK operation. Every internal log call is wrapped, so a
failing sink - a full disk, a down syslog target - is dropped and the read, refresh, or `create()`
that logged carries on. The [stream observer](https://docs.westyx.dev/sdks/python/stream-observer.md) is contained the same
way. The Workload Identity credential source is deliberately not - it is on the auth path, so its
error surfaces rather than being swallowed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.