Audit Compliance: Logs API Logger

[MrAlias]

trafficstars

1. Review the Logger section of the Logs Bridge API specification for all normative statements
2. Audit the logs bridge API package for compliance with the specified normative statements.
3. Identify existing issues or create new issues to track any work needed to make the logs bridge API package compliant with the specification.

[pellared]

Blocked by:

• https://github.com/open-telemetry/opentelemetry-go/issues/5769

[pellared]

Unblocked

[XSAM]

The Logger is responsible for emitting LogRecords.

https://github.com/open-telemetry/opentelemetry-go/blob/5ba5e7a449f36c1c02710bbaa517263797046db0/log/logger.go#L13-L18

Logger operations

The Logger MUST provide functions to:

• Emit a LogRecord

https://github.com/open-telemetry/opentelemetry-go/blob/5ba5e7a449f36c1c02710bbaa517263797046db0/log/logger.go#L24-L31

The Logger SHOULD provide functions to:

• Report if Logger is Enabled

https://github.com/open-telemetry/opentelemetry-go/blob/5ba5e7a449f36c1c02710bbaa517263797046db0/log/logger.go#L33-L57

We are compliant.

[XSAM]

Emit a LogRecord

The effect of calling this API is to emit a LogRecord to the processing pipeline.

https://github.com/open-telemetry/opentelemetry-go/blob/f8df2f917d671a2dcc520414a29f69f6768efec6/log/record.go#L17-L19

The API MUST accept the following parameters:

• Timestamp (optional)

https://github.com/open-telemetry/opentelemetry-go/blob/f8df2f917d671a2dcc520414a29f69f6768efec6/log/record.go#L61-L69

• Observed Timestamp (optional).

https://github.com/open-telemetry/opentelemetry-go/blob/f8df2f917d671a2dcc520414a29f69f6768efec6/log/record.go#L71-L79

• The Context associated with the LogRecord. When implicit Context is supported, then this parameter SHOULD be optional and if unspecified then MUST use current Context. When only explicit Context is supported, this parameter SHOULD be required.

https://github.com/open-telemetry/opentelemetry-go/blob/5ba5e7a449f36c1c02710bbaa517263797046db0/log/logger.go#L31

• Severity Number (optional)

https://github.com/open-telemetry/opentelemetry-go/blob/f8df2f917d671a2dcc520414a29f69f6768efec6/log/record.go#L81-L89

• Severity Text (optional)

https://github.com/open-telemetry/opentelemetry-go/blob/f8df2f917d671a2dcc520414a29f69f6768efec6/log/record.go#L91-L101

• Body (optional)

https://github.com/open-telemetry/opentelemetry-go/blob/f8df2f917d671a2dcc520414a29f69f6768efec6/log/record.go#L103-L111

• Attributes (optional)

https://github.com/open-telemetry/opentelemetry-go/blob/f8df2f917d671a2dcc520414a29f69f6768efec6/log/record.go#L128-L139

• Status: Development - Event Name (optional)

https://github.com/open-telemetry/opentelemetry-go/blob/f8df2f917d671a2dcc520414a29f69f6768efec6/log/record.go#L49-L59

The API SHOULD provide functionality for users to convert Standard Attributes so they can be used, or directly accept them, in the log signal. This allows the reuse of Standard Attributes across signals.

https://github.com/open-telemetry/opentelemetry-go/blob/80ce40468cd02589a86ce7723b881b737be2860b/log/logger.go#L117-L126

[XSAM]

Enabled

https://github.com/open-telemetry/opentelemetry-go/blob/5ba5e7a449f36c1c02710bbaa517263797046db0/log/logger.go#L57

Status: Development

To help users avoid performing computationally expensive operations when generating a LogRecord, a Logger SHOULD provide this Enabled API.

The API SHOULD accept the following parameters:

• The Context to be associated with the LogRecord. When implicit Context is supported, then this parameter SHOULD be optional and if unspecified then MUST use current Context.

https://github.com/open-telemetry/opentelemetry-go/blob/5ba5e7a449f36c1c02710bbaa517263797046db0/log/logger.go#L57

When only explicit Context is supported, accepting this parameter is REQUIRED.

• Severity Number (optional)
• Event Name (optional)

https://github.com/open-telemetry/opentelemetry-go/blob/1bae8f73472d4db652fe5e3df0fc98725e8aa8e9/log/logger.go#L138-L141

[!NOTE] Adding parameters in the struct in the future does not seem to bring breaking changes.

This API MUST return a language idiomatic boolean type. A returned value of true means the Logger is enabled for the provided arguments, and a returned value of false means the Logger is disabled for the provided arguments.

https://github.com/open-telemetry/opentelemetry-go/blob/5ba5e7a449f36c1c02710bbaa517263797046db0/log/logger.go#L45-L50

https://github.com/open-telemetry/opentelemetry-go/blob/5ba5e7a449f36c1c02710bbaa517263797046db0/log/logger.go#L57

The returned value is not always static, it can change over time. The API SHOULD be documented that instrumentation authors needs to call this API each time they emit a LogRecord to ensure they have the most up-to-date response.

https://github.com/open-telemetry/opentelemetry-go/blob/5ba5e7a449f36c1c02710bbaa517263797046db0/log/logger.go#L36-L38

We are compliant.

[XSAM]

Concurrency requirements

Logger - all methods are safe to be called concurrently.

https://github.com/open-telemetry/opentelemetry-go/blob/5ba5e7a449f36c1c02710bbaa517263797046db0/log/logger.go#L29-L31

https://github.com/open-telemetry/opentelemetry-go/blob/5ba5e7a449f36c1c02710bbaa517263797046db0/log/logger.go#L55-L57

We are compliant.

[XSAM]

@open-telemetry/go-maintainers I have a question on this https://github.com/open-telemetry/opentelemetry-go/issues/5679#issuecomment-2774461198. I am not sure we are fully compliant.

[pellared]

@open-telemetry/go-maintainers I have a question on this #5679 (comment). I am not sure we are fully compliant.

Good question. I understood it that the SDK (API implementation) should handle it.

https://github.com/open-telemetry/opentelemetry-go/blob/f8df2f917d671a2dcc520414a29f69f6768efec6/sdk/log/logger.go#L98

Similarly the SDK is responsible for making Emit concurrent safe.

I think we should add a doc comment that the implementation should do it here:

https://github.com/open-telemetry/opentelemetry-go/blob/5ba5e7a449f36c1c02710bbaa517263797046db0/log/logger.go#L31

The other possibility is to set it when calling ObservedTimestamp (when the time was not set) but this side effect would seem not intuitive and would lock down the behavior which is optional and not required by the implemention.

@open-telemetry/go-maintainers, thoughts?

[pellared]

@XSAM, please use a newer version of the spec when checking the compliance. There has been important changes since the issue was created.

[XSAM]

@XSAM, please use a newer version of the spec when checking the compliance. There has been important changes since the issue was created.

Good catch. I have updated my comment to reference https://github.com/open-telemetry/opentelemetry-specification/blob/v1.43.0/specification/logs/api.md

[pellared]

SIG meeting notes: AI @XSAM: Clarify the specification so that the following is in SDK spec and not the API spec:

If unspecified the implementation SHOULD set it equal to the current time.

[pellared]

Closing as https://github.com/open-telemetry/opentelemetry-specification/issues/4481 is also resolved.

[pellared]

Reopening as the signature for Enabled is changing: https://github.com/open-telemetry/opentelemetry-go/pull/6825

[XSAM]

I will review the spec again once the new spec is released.

[XSAM]

I have reviewed this part again regarding the latest (v1.47.0) spec https://github.com/open-telemetry/opentelemetry-specification/blob/v1.47.0/specification/logs/api.md#logger.

@open-telemetry/go-maintainers I believe we comply with this part of the specification. Feel free to double-check and close this issue.

[pellared]

I think after we land https://github.com/open-telemetry/opentelemetry-go/issues/7034 this audit compliance should be redone. Therefore, marking it as blocked.