Context
Ambient telemetry context — who and what the current work belongs to.
from nexus import contextAmbient telemetry context — who and what the current work belongs to.
Every event, log line and error carries identity (distinct_id), a session
(session_key) and device/app fields. Threading those through every call by
hand is miserable, so the SDK keeps them in a contextvars variable that
is correct per-thread and per-async-task: bind once at the edge of a
request, and everything captured underneath inherits it.
from nexus import context
with context.scope(distinct_id="user_123", url="/checkout"):
nexus.events.track("order_placed", {"total": 42}) # carries user_123The framework integrations bind this for you on every request.
| Symbol | Kind | Summary |
|---|---|---|
TelemetryContext | class | Identity + device fields attached to telemetry captured in this scope. |
current() | function | The context in force for this thread / async task. |
bind() | function | Merge values into the current context. |
unbind() | function | Restore the context captured by bind. |
scope() | function | Bind values for the duration of the with block. |
identify() | function | Set the current user (and optionally more fields) for this context. |
clear() | function | Drop the whole context — no user, no session, no device. |
reset() | function | Forget the user and start a new session — call this on logout. |
new_session_key() | function | A fresh opaque session key. |
new_device_key() | function | A fresh opaque device key. |
TelemetryContext
classIdentity + device fields attached to telemetry captured in this scope.
View sourcemerged()
methoddef merged(**changes) -> 'TelemetryContext'A copy with the non-None changes applied.
Parameters
Prop
Type
Returns 'TelemetryContext'
as_dict()
methoddef as_dict() -> Dict[str, Any]Snake_case dict of the set fields (properties included).
Returns Dict[str, Any]
wire()
methoddef wire() -> Dict[str, Any]camelCase dict of the set identity fields, ready for the API.
Returns Dict[str, Any]
Functions
current()
functiondef current() -> TelemetryContextThe context in force for this thread / async task.
Returns TelemetryContext
bind()
functiondef bind(**values) -> 'contextvars.Token[TelemetryContext]'Merge values into the current context.
Returns a token; pass it to unbind to restore the previous state.
Prefer scope, which does that for you.
Parameters
Prop
Type
Returns 'contextvars.Token[TelemetryContext]'
unbind()
functiondef unbind(token) -> NoneRestore the context captured by bind.
Parameters
Prop
Type
scope()
functiondef scope(**values) -> Iterator[TelemetryContext]Bind values for the duration of the with block.
with context.scope(distinct_id="u_1", url=request.path):
...Parameters
Prop
Type
Returns Iterator[TelemetryContext]
identify()
functiondef identify(distinct_id, **values) -> NoneSet the current user (and optionally more fields) for this context.
This only sets local context. To also upsert the person server-side, call
client.sessions.identify(...) (or client.identify(...), which does
both).
Parameters
Prop
Type
clear()
functiondef clear() -> NoneDrop the whole context — no user, no session, no device.
reset is what you want on logout (it keeps the device and starts a
fresh session); this is for tests and worker teardown.
reset()
functiondef reset(*, keep_device=True) -> NoneForget the user and start a new session — call this on logout.
Parameters
Prop
Type
new_session_key()
functiondef new_session_key() -> strA fresh opaque session key.
Returns str
new_device_key()
functiondef new_device_key() -> strA fresh opaque device key.
Returns str