Add shortcut methods to log different levels of log records in Logger

[pksunkara]

Is your feature request related to a problem? Please describe.

Right now, Logger provides only emit method according to the spec. But it still needs the end-user to import SeverityNumber and decide on severityText before logging. While, this is nice for complex use-cases, this is too convoluted for simple use cases.

Describe the solution you'd like

I propose improving the ergonomics of the logging library by adding helper methods for each level. For example:

  public info(logRecord: Exclude<LogRecord, 'severityNumber' | 'severityText'>): void {
    this.emit({
      ...logRecord,
      severityNumber: SeverityNumber.INFO,
      severityText: 'INFO',
    });
  }

NOTE: These are strictly helper methods in the sdk-logs library and are not considered part of the OpenTelemetry spec.

Describe alternatives you've considered

Additional context

[pksunkara]

@pichlermarc If I get the go-ahead, I can send a PR for this.

[pichlermarc]

The Logs Bridge API is not intended for consumption directly by end-users, only for use with instrumentations for existing logging APIs. The helpers proposed here would have to be added to the spec first.

[pksunkara]

What about the sdk-node package? I intend these to be purely helpers and not in the opentelemetry spec.

[pichlermarc]

Hmm, I would also not consider this something that would fit into the scope of the sdk-node package, as this really only would be helpful as an API feature. It could be that there's a misunderstanding what the Logs Bridge API here is intended for. From the spec:

Note: this document defines a log backend API. The API is not intended to be called by application developers directly. It is provided for logging library authors to build log appenders, which use this API to bridge between existing logging libraries and the OpenTelemetry log data model.

In the case of log appenders, which is the intended use-case for the logs bridge API, I would not expect emit() to appear in code more than a handful of times (for instance: in the Java Log4j appender, emit is called exactly one time here). 🤔

So keeping the intended use in mind, I would say adding a helper like this would not be helpful in that case. 🤔

[pksunkara]

existing logging libraries

Is it not recommended to use opentelemetry logging without 3rd party logging libraries?

[pichlermarc]

existing logging libraries

Is it not recommended to use opentelemetry logging without 3rd party logging libraries?

This is correct. Defining an end-user-focused API would be up to the specification. Still, the current plan for the Logs Bridge API is that it is intended only for use within appenders for 3rd party libraries.

[pksunkara]

@pichlermarc Would you be willing to accept a SugaredLogger similar to SugaredTracer from #3250?

[pichlermarc]

@pksunkara unfortunately, no. A user-focused logging API in a future spec version is possible - we wouldn't want to provide a competing implementation. The reasoning for accepting #3250 and #3827 and not this request is that:

• the trace API is meant to be used directly by users, therefore adding the SugaredTracer or decorators is something that also helps non-instrumentation library authors
• once we add a user-facing API, there will be an expectation that we support features that are present in fully-fledged Logging frameworks, which are not in scope of the project (pending specification)

A better way would be to enable users to use an existing logging framework by implementing any of these issues over at the contrib repository:

• Add Bunyan stream for OpenTelemetry opentelemetry-js-contrib#1559
• Add Winston format/transport for OpenTelemetry opentelemetry-js-contrib#1558
• Instrumentation to capture console logs as OTel logs opentelemetry-js-contrib#1560

With the approach proposed by these issues, users can use existing logging frameworks (and all their features), which is following the spec section that I cited previously in #3825 (comment).

[pichlermarc]

As per my previous comment, I'm closing this issue as not planned. Once there is a specification for it we can pick up the discussion again in a new issue.