js/opentelemetry/logs

constructor()

Creates an empty builder with an empty attribute map and no other fields set.

import { LogRecordBuilder } from 'internal:opentelemetry/logs';

const builder = new LogRecordBuilder();

setBody(body: unknown): this

Sets the record body to any value, unchanged.

Use this when the body may be a string, number, boolean, or structured object and you do not want coercion; setTextBody and setJsonBody are intent-revealing variants.

import { LogRecordBuilder } from 'internal:opentelemetry/logs';

const b = new LogRecordBuilder().setBody({ event: 'ping', ok: true });

setTextBody(body: string): this

Sets the record body to the string form of the given value.

The value is passed through String(), so non-string inputs are stringified. Use this for human-readable log messages.

import { LogRecordBuilder } from 'internal:opentelemetry/logs';

const b = new LogRecordBuilder().setTextBody('user signed in');

setJsonBody(body: unknown): this

Sets the record body to a structured value, unchanged.

Behaves like setBody but signals intent that the body is structured JSON data rather than a text message.

import { LogRecordBuilder } from 'internal:opentelemetry/logs';

const b = new LogRecordBuilder().setJsonBody({ orderId: 'ord_1', items: 3 });

setSeverity(severityText: string, severityNumber?: number): this

Sets the severity text and, optionally, the severity number.

When severityNumber is omitted the number field is cleared, letting the emitting logger apply its default (SeverityNumber.INFO). Passing an explicit number pins it. The text is stored as given, so callers control casing.

import { LogRecordBuilder, SeverityNumber } from 'internal:opentelemetry/logs';

const b = new LogRecordBuilder().setSeverity('ERROR', SeverityNumber.ERROR);

setAttribute(key: string, value: unknown): this

Sets a single attribute by key, replacing any previous value for that key.

import { LogRecordBuilder } from 'internal:opentelemetry/logs';

const b = new LogRecordBuilder().setAttribute('http.status_code', 503);

setAttributes(attributes: Attributes): this

Merges a map of attributes into the record, overwriting duplicate keys.

A nullish argument is treated as an empty map. Existing attributes not present in the argument are kept.

import { LogRecordBuilder } from 'internal:opentelemetry/logs';

const b = new LogRecordBuilder().setAttributes({ region: 'eu', shard: 4 });

setEventName(name: string): this

Sets the event name that identifies this record as a named event.

The value is coerced to a string. Event names typically follow a dotted namespace such as user.login.

import { LogRecordBuilder } from 'internal:opentelemetry/logs';

const b = new LogRecordBuilder().setEventName('user.login');

setCategory(name: string): this

Sets the category name used to group related records.

The value is coerced to a string.

import { LogRecordBuilder } from 'internal:opentelemetry/logs';

const b = new LogRecordBuilder().setCategory('auth');

setDroppedAttributesCount(count: number): this

Records how many attributes were dropped before this record was built.

The count is coerced with Number() and any non-numeric or NaN value becomes 0. Set this when you have already trimmed attributes upstream and want the loss reflected in the exported record.

import { LogRecordBuilder } from 'internal:opentelemetry/logs';

const b = new LogRecordBuilder().setDroppedAttributesCount(3);

setContext(context: TraceContext | null | undefined): this

Attaches an explicit trace context, or clears it when given nullish/empty context.

Each of trace id, span id, trace flags, and baggage is set when present on the given context and deleted otherwise, so passing null or an empty object removes any previously set correlation fields. Use this to correlate a record with a specific span rather than the ambient one the logger would capture.

import { LogRecordBuilder } from 'internal:opentelemetry/logs';

const b = new LogRecordBuilder().setContext({
  traceId: '5b8aa5a2d2c872e8321cf37308d69df2',
  spanId: '051581bf3cb55c13',
  traceFlags: 1,
});

build(): LogRecord

Snapshots the accumulated record into a plain LogRecord.

The returned record is a shallow copy with its own copied attribute map, so further mutation of the builder does not affect it. Only fields that were explicitly set are present; defaults are applied later at emission. The builder can be reused after build.

import { LogRecordBuilder } from 'internal:opentelemetry/logs';

const record = new LogRecordBuilder().setTextBody('done').build();

constructor(provider: LoggerProvider, scope: ScopeInfo)

Binds a logger to its provider and scope and prepares the shared record topic.

Called by LoggerProvider.getLogger; application code does not invoke this directly.

import { LoggerProvider } from 'internal:opentelemetry/logs';

const logger = new LoggerProvider().getLogger('scope.name');

get scope(): ScopeInfo

A defensive copy of this logger's instrumentation scope.

The returned object is safe to mutate; its attributes are also copied, so changes to it never affect records this logger emits.

import { getLoggerProvider } from 'internal:opentelemetry/logs';

const logger = getLoggerProvider().getLogger('cache', '1.0.0');
const { name, version } = logger.scope;

emit(body: unknown, options: { severityText?: string; severityNumber?: number; attributes?: Attributes; } = {}): void

Emits a log record from a body and options, filling defaults and trace context.

The body may be any value — a string message or a structured object. When omitted, severityText defaults to 'INFO' and severityNumber to SeverityNumber.INFO. The timestamp is set to now, the logger's scope and the provider's resource are attached, and any active trace context (trace id, span id, trace flags, baggage) is captured. The record is published on the phase topic derived from the lowercased severityText (or 'emit' when none is given) and on the shared record topic.

import { getLoggerProvider, SeverityNumber } from 'internal:opentelemetry/logs';

const logger = getLoggerProvider().getLogger('auth');
logger.emit('token refreshed', {
  severityText: 'INFO',
  severityNumber: SeverityNumber.INFO,
  attributes: { 'user.id': 'u_7' },
});

emitRecord(builder: LogRecordBuilder | Partial<LogRecord>): void

Emits a pre-built or partial log record, preserving its explicit fields.

Accepts either a LogRecordBuilder (which is built first) or a partial LogRecord. Explicit fields on the record win; only missing ones are filled: schema version, severity text/number (default 'INFO' / SeverityNumber.INFO), timestamp, resource. The logger's scope always replaces any scope on the input. Trace correlation fields (trace id, span id, trace flags, baggage) fall back to the active trace context when not already set on the record. Optional fields (body, observedTimeUnixNano, eventName, categoryName, flags, droppedAttributesCount) are carried through only when present. The publish phase is the lowercased final severityText.

import { getLoggerProvider, LogRecordBuilder } from 'internal:opentelemetry/logs';

const logger = getLoggerProvider().getLogger('checkout');
logger.emitRecord(
  new LogRecordBuilder()
    .setEventName('order.placed')
    .setJsonBody({ orderId: 'ord_9', total: 42.5 })
    .setSeverity('INFO'),
);

debug(body: unknown, attributes: Attributes = {}): void

Emits a record at DEBUG severity (severity number 5).

Shorthand for emit with severityText: 'DEBUG'.

import { getLoggerProvider } from 'internal:opentelemetry/logs';

getLoggerProvider().getLogger('db').debug('query executed', { rows: 12 });

info(body: unknown, attributes: Attributes = {}): void

Emits a record at INFO severity (severity number 9).

Shorthand for emit with severityText: 'INFO'.

import { getLoggerProvider } from 'internal:opentelemetry/logs';

getLoggerProvider().getLogger('http').info('request handled', { status: 200 });

warn(body: unknown, attributes: Attributes = {}): void

Emits a record at WARN severity (severity number 13).

Shorthand for emit with severityText: 'WARN'.

import { getLoggerProvider } from 'internal:opentelemetry/logs';

getLoggerProvider().getLogger('pool').warn('connection retry', { attempt: 2 });

error(body: unknown, attributes: Attributes = {}): void

Emits a record at ERROR severity (severity number 17).

Shorthand for emit with severityText: 'ERROR'.

import { getLoggerProvider } from 'internal:opentelemetry/logs';

getLoggerProvider().getLogger('api').error('unhandled exception', { code: 'E_IO' });

getLogger(name: string, version?: string, options?: { schemaUrl?: string | null; attributes?: Attributes; droppedAttributesCount?: number; }): Logger

Returns a Logger bound to a named instrumentation scope.

The name is required and identifies the library or subsystem producing the logs; it drives the scoped topic names records are published on. The optional version and options (schema URL, scope attributes, dropped-attribute count) further qualify the scope. The scope is normalized before use, which trims the name and throws a TypeError if it is empty or whitespace-only.

import { LoggerProvider } from 'internal:opentelemetry/logs';

const provider = new LoggerProvider();
const logger = provider.getLogger('billing', '2.0.0', {
  schemaUrl: 'https://opentelemetry.io/schemas/1.31.0',
  attributes: { team: 'payments' },
});

schemaVersion?: number

schemaVersion property on LogRecord.

Omitted optional values default to undefined; required values are expected from the producer before the record is exported or published. Consumers should tolerate missing optional fields in telemetry payloads.

let value: LogRecord['schemaVersion'];

body?: unknown

body property on LogRecord.

Omitted optional values default to undefined; required values are expected from the producer before the record is exported or published. Consumers should tolerate missing optional fields in telemetry payloads.

let value: LogRecord['body'];

severityText?: string

severityText property on LogRecord.

Omitted optional values default to undefined; required values are expected from the producer before the record is exported or published. Consumers should tolerate missing optional fields in telemetry payloads.

let value: LogRecord['severityText'];

severityNumber?: number

severityNumber property on LogRecord.

Omitted optional values default to undefined; required values are expected from the producer before the record is exported or published. Consumers should tolerate missing optional fields in telemetry payloads.

let value: LogRecord['severityNumber'];

timeUnixNano?: number

timeUnixNano property on LogRecord.

Omitted optional values default to undefined; required values are expected from the producer before the record is exported or published. Consumers should tolerate missing optional fields in telemetry payloads.

let value: LogRecord['timeUnixNano'];

observedTimeUnixNano?: number

observedTimeUnixNano property on LogRecord.

Omitted optional values default to undefined; required values are expected from the producer before the record is exported or published. Consumers should tolerate missing optional fields in telemetry payloads.

let value: LogRecord['observedTimeUnixNano'];

attributes?: Attributes

attributes property on LogRecord.

Omitted optional values default to undefined; required values are expected from the producer before the record is exported or published. Consumers should tolerate missing optional fields in telemetry payloads.

let value: LogRecord['attributes'];

droppedAttributesCount?: number

droppedAttributesCount property on LogRecord.

Omitted optional values default to undefined; required values are expected from the producer before the record is exported or published. Consumers should tolerate missing optional fields in telemetry payloads.

let value: LogRecord['droppedAttributesCount'];

scope?: ScopeInfo

scope property on LogRecord.

Omitted optional values default to undefined; required values are expected from the producer before the record is exported or published. Consumers should tolerate missing optional fields in telemetry payloads.

let value: LogRecord['scope'];

resource?: Resource

resource property on LogRecord.

Omitted optional values default to undefined; required values are expected from the producer before the record is exported or published. Consumers should tolerate missing optional fields in telemetry payloads.

let value: LogRecord['resource'];

traceId?: string

traceId property on LogRecord.

Omitted optional values default to undefined; required values are expected from the producer before the record is exported or published. Consumers should tolerate missing optional fields in telemetry payloads.

let value: LogRecord['traceId'];

spanId?: string

spanId property on LogRecord.

Omitted optional values default to undefined; required values are expected from the producer before the record is exported or published. Consumers should tolerate missing optional fields in telemetry payloads.

let value: LogRecord['spanId'];

traceFlags?: number

traceFlags property on LogRecord.

Omitted optional values default to undefined; required values are expected from the producer before the record is exported or published. Consumers should tolerate missing optional fields in telemetry payloads.

let value: LogRecord['traceFlags'];

baggage?: Baggage | null

baggage property on LogRecord.

Omitted optional values default to undefined; required values are expected from the producer before the record is exported or published. Consumers should tolerate missing optional fields in telemetry payloads.

let value: LogRecord['baggage'];

eventName?: string

eventName property on LogRecord.

Omitted optional values default to undefined; required values are expected from the producer before the record is exported or published. Consumers should tolerate missing optional fields in telemetry payloads.

let value: LogRecord['eventName'];

categoryName?: string

categoryName property on LogRecord.

Omitted optional values default to undefined; required values are expected from the producer before the record is exported or published. Consumers should tolerate missing optional fields in telemetry payloads.

let value: LogRecord['categoryName'];

flags?: number

flags property on LogRecord.

Omitted optional values default to undefined; required values are expected from the producer before the record is exported or published. Consumers should tolerate missing optional fields in telemetry payloads.

let value: LogRecord['flags'];