cityrp.logging

Console logging library for CityRP, providing a namespaced, level-filterable logging facility for developer diagnostics and runtime troubleshooting.

Sharedcityrp.logging.GetDefaultLevel() → numberSource ☍

Gets the global default level.

Returns

1. numberThe global default level.

Sharedcityrp.logging.RegisterSink(name, sink)Source ☍

Registers a sink that will receive every dispatched log entry.

Parameters

• namestringThe sink's registry name.
• sinkSinkThe sink table with a Write function.

Sharedcityrp.logging.SetDefaultLevel(level)Source ☍

Sets the global default level, used by the root logger and any logger without an explicit level in its ancestry.

Parameters

• levelstring|numberNumeric level or string level name.

Sharedcityrp.logging.UnregisterSink(name)Source ☍

Unregisters a sink by name.

Parameters

• namestringThe sink's registry name.

Factory

Sharedcityrp.logging.GetLogger(namespace) → LoggerSource ☍

Gets or creates a logger for the given namespace, registering it against its parent if newly created.

Parameters

• namespacestring?Logger namespace (dot-notated string), defaults to the root namespace.

Returns

1. LoggerThe logger instance.

Sanitization

Sharedcityrp.logging.sanitizeEntity(ent) → tableSource ☍

Sanitizes an entity for logging, returning an array of message parts with colour and text.

Parameters

• entEntityThe entity to sanitize.

Returns

1. tableArray of message parts: {Color, string, Color}.

Sharedcityrp.logging.sanitizePlayer(ply) → tableSource ☍

Sanitizes a player for logging, returning an array of message parts with colour and text.

Parameters

• plyPlayerThe player to sanitize.

Returns

1. tableArray of message parts: {Color, string, Color}.

Levels

Sharedcityrp.logging.levelsSource ☍

SharedLogLevelSource ☍

Numeric log level constants, from lowest severity to highest. INHERIT defers to the parent logger's effective level, ALWAYS bypasses level filtering entirely, and NEVER suppresses all output.

SharedSinkSource ☍

A logging destination that receives dispatched log entries.

Sharedcityrp.loggingSource ☍

Sharedcityrp.logging.levels.DEFAULTSource ☍

Registry

Sharedcityrp.logging.loggersSource ☍

Logger instances by namespace.

Sharedcityrp.logging.sinksSource ☍

Registered sinks, by name.

SharedSink.WriteSource ☍

Called with the log entry table for every dispatched message.

A logger wrapper that merges a fixed set of metadata fields into every logged message. Created via Logger:WithFields.

Functions

SharedBoundLogger:_MergeMeta(meta) → tableSource ☍

Merges this wrapper's bound fields with a per-call metadata table, with per-call values taking precedence.

Parameters

• metatable?Per-call metadata table, or nil.

Returns

1. tableMerged metadata.

SharedBoundLogger:_ProcessArgs(args) → tableSource ☍

Processes an array of varargs, appending this wrapper's merged metadata table as the final argument.

Parameters

• argstableArray of the original varargs.

Returns

1. tableNew args array with merged metadata appended.

SharedBoundLogger:Critical(_) → BoundLoggerSource ☍

Logs a message at CRITICAL level with this wrapper's bound fields merged into the metadata.

Parameters

• string|function|table|Color|Entity...(+1)Message parts and optional metadata table.

Returns

1. BoundLoggerThis wrapper, for chaining.

SharedBoundLogger:Debug(_) → BoundLoggerSource ☍

Logs a message at DEBUG level with this wrapper's bound fields merged into the metadata.

Parameters

• string|function|table|Color|Entity...(+1)Message parts and optional metadata table.

Returns

1. BoundLoggerThis wrapper, for chaining.

SharedBoundLogger:Error(_) → BoundLoggerSource ☍

Logs a message at ERROR level with this wrapper's bound fields merged into the metadata.

Parameters

• string|function|table|Color|Entity...(+1)Message parts and optional metadata table.

Returns

1. BoundLoggerThis wrapper, for chaining.

SharedBoundLogger:Fatal(_) → BoundLoggerSource ☍

Logs a message at FATAL level with this wrapper's bound fields merged into the metadata.

Parameters

• string|function|table|Color|Entity...(+1)Message parts and optional metadata table.

Returns

1. BoundLoggerThis wrapper, for chaining.

SharedBoundLogger:Info(_) → BoundLoggerSource ☍

Logs a message at INFO level with this wrapper's bound fields merged into the metadata.

Parameters

• string|function|table|Color|Entity...(+1)Message parts and optional metadata table.

Returns

1. BoundLoggerThis wrapper, for chaining.

SharedBoundLogger:Output(_) → BoundLoggerSource ☍

Logs a message at INFO level, bypassing level filtering, with this wrapper's bound fields merged into the metadata. Intended for explicit command output (e.g. concommand handlers) that should always print regardless of the logger's configured level.

Parameters

• string|function|table|Color|Entity...(+1)Message parts and optional metadata table.

Returns

1. BoundLoggerThis wrapper, for chaining.

SharedBoundLogger:Raw(level, _) → BoundLoggerSource ☍

Logs a message at an arbitrary level, bypassing level filtering, with this wrapper's bound fields merged into the metadata.

Parameters

• levelnumberNumeric log level.
• string|function|table|Color|Entity...(+1)Message parts and optional metadata table.

Returns

1. BoundLoggerThis wrapper, for chaining.

SharedBoundLogger:Warning(_) → BoundLoggerSource ☍

Logs a message at WARNING level with this wrapper's bound fields merged into the metadata.

Parameters

• string|function|table|Color|Entity...(+1)Message parts and optional metadata table.

Returns

1. BoundLoggerThis wrapper, for chaining.

SharedBoundLogger:WithFields(fields) → BoundLoggerSource ☍

Creates a new bound logger with additional fields merged on top of this wrapper's existing bound fields.

Parameters

• fieldstableFields table to merge into metadata.

Returns

1. BoundLoggerNew bound logger with merged fields.

Fields

SharedBoundLogger.__indexSource ☍

A logger wrapper that merges a fixed set of metadata fields into every logged message. Created via Logger:WithFields.

SharedBoundLogger._fieldsSource ☍

Metadata fields merged into every logged message.

SharedBoundLogger._loggerSource ☍

The underlying logger this wrapper delegates to.

A namespaced, level-filterable logger. Obtain instances via cityrp.logging.GetLogger rather than constructing directly.

Functions

SharedLogger:_InvalidateChildCaches()Source ☍

Invalidates the effective level cache for this logger and recursively notifies its children.

SharedLogger:_OnAncestorLevelChange()Source ☍

Handles a notification that an ancestor's level changed, by invalidating this logger's own cache.

SharedLogger:_RegisterChild(child)Source ☍

Registers a child logger against this logger.

Parameters

• childLoggerThe child logger instance.

SharedLogger:GetChild(segment) → LoggerSource ☍

Gets a child logger by segment name, appending it to this logger's namespace. Warns (once) if the segment itself contains a dot, since GetLogger should be used directly for multi-segment paths.

Parameters

• segmentstringChild segment name.

Returns

1. LoggerThe child logger.

SharedLogger:GetChildren() → Logger[]Source ☍

Gets all direct children of this logger.

Returns

1. Logger[]Array of child logger instances.

SharedLogger:GetDisplayName() → stringSource ☍

Gets the display name of this logger, showing "root" for the root logger.

Returns

1. stringThe display name.

SharedLogger:GetEffectiveLevel() → numberSource ☍

Gets the effective level after inheritance, walking up to the parent (and caching the result) if this logger has no explicit level.

Returns

1. numberThe effective level.

SharedLogger:GetLevel() → number?Source ☍

Gets the explicit level set on this logger.

Returns

1. number?Explicit level, or nil if inheriting.

SharedLogger:GetName() → stringSource ☍

Gets the namespace of this logger.

Returns

1. stringThe logger's namespace.

SharedLogger:GetParent() → LoggerSource ☍

Gets the parent logger, creating it if it doesn't yet exist. Returns itself if this is the root logger.

Returns

1. LoggerThe parent logger.

SharedLogger:IsRoot() → booleanSource ☍

Checks whether this is the root logger.

Returns

1. booleanWhether this is the root logger.

SharedLogger:SetLevel(level) → LoggerSource ☍

Sets the log level for this logger, and invalidates the cached effective level of this logger and its descendants.

Parameters

• levelstring|numberNumeric level or string level name.

Returns

1. LoggerThis logger, for chaining.

Context

SharedLogger:WithFields(fields) → BoundLoggerSource ☍

Creates a logger wrapper that merges the given fields into the metadata of every message logged through it.

Parameters

• fieldstableFields table to merge into metadata.

Returns

1. BoundLoggerBound logger wrapper.

Dispatch

SharedLogger:_Dispatch(level, messageParts, meta)Source ☍

Dispatches a log entry to every registered sink. Sink errors are swallowed; logging must never throw.

Parameters

• levelnumberNumeric log level.
• messagePartstableArray of message parts.
• metatable?Metadata table.

SharedLogger:_Log(level, _)Source ☍

Logs a message at a specific level, applying level filtering before dispatch.

Parameters

• levelnumberNumeric log level.
• string|function|table|Color|Entity...(+1)Message parts and optional metadata table.

Methods

SharedLogger:Critical(_) → LoggerSource ☍

Logs a message at CRITICAL level.

Parameters

• string|function|table|Color|Entity...(+1)Message parts and optional metadata table.

Returns

1. LoggerThis logger, for chaining.

SharedLogger:Debug(_) → LoggerSource ☍

Logs a message at DEBUG level.

Parameters

• string|function|table|Color|Entity...(+1)Message parts and optional metadata table.

Returns

1. LoggerThis logger, for chaining.

SharedLogger:Error(_) → LoggerSource ☍

Logs a message at ERROR level.

Parameters

• string|function|table|Color|Entity...(+1)Message parts and optional metadata table.

Returns

1. LoggerThis logger, for chaining.

SharedLogger:Fatal(_) → LoggerSource ☍

Logs a message at FATAL level.

Parameters

• string|function|table|Color|Entity...(+1)Message parts and optional metadata table.

Returns

1. LoggerThis logger, for chaining.

SharedLogger:Info(_) → LoggerSource ☍

Logs a message at INFO level.

Parameters

• string|function|table|Color|Entity...(+1)Message parts and optional metadata table.

Returns

1. LoggerThis logger, for chaining.

SharedLogger:Output(_) → LoggerSource ☍

Logs a message at INFO level, bypassing this logger's level filtering entirely. Intended for explicit command output (e.g. concommand handlers) that should always print regardless of the logger's configured level.

Parameters

• string|function|table|Color|Entity...(+1)Message parts and optional metadata table.

Returns

1. LoggerThis logger, for chaining.

SharedLogger:Raw(level, _) → LoggerSource ☍

Logs a message at an arbitrary level, bypassing this logger's level filtering entirely.

Parameters

• levelnumberNumeric log level.
• string|function|table|Color|Entity...(+1)Message parts and optional metadata table.

Returns

1. LoggerThis logger, for chaining.

SharedLogger:Warning(_) → LoggerSource ☍

Logs a message at WARNING level.

Parameters

• string|function|table|Color|Entity...(+1)Message parts and optional metadata table.

Returns

1. LoggerThis logger, for chaining.

Fields

SharedLogger.__indexSource ☍

A namespaced, level-filterable logger. Obtain instances via cityrp.logging.GetLogger rather than constructing directly.

SharedLogger._childrenSource ☍

Child loggers, by namespace.

SharedLogger._effectiveLevelSource ☍

Cached effective log level.

SharedLogger._levelSource ☍

Explicit log level, or nil to inherit from the parent.

SharedLogger._namespaceSource ☍

Logger namespace.

SharedLogger._parentSource ☍

Cached parent logger.

SharedLogger._warnedMultiSegmentSource ☍

Whether the multi-segment GetChild warning has already been issued.