Define interfaces for annotating error information via RecordError

[v3n]

Problem Statement

The existing RecordError() method doesn't currently allow errors to propagate implementation-specific information back to the telemetry framework. Right now, the framework reflects the static typename of the error, but that's not enough to differentiate errors in many cases, for example:

• RPC/REST errors which share a uniform type struct for RPC errors such as grpc.Status
• Protocol errors such as MySQL Errors

Proposed Solution

Standardize on the definition of the type of an error (static) and the class of an error (runtime).

• The type of the error remains the same–the type as returned by the Golang reflect package
• The class of an error is implementation-defined and propagated to OpenTelemetry via interface implementation.
• The place an error is recorded is not necessarily the same place that an error was captured (such as middleware), errors should be able to propogate the stack trace via an interface.
• Errors should be able to propogate additional error-specific attributes.

Reference

• Define the following interfaces:

type (
	// StackTracer propagates an error's class.
	StackTracer interface {
		OTStackTrace() []uintptr
	}

	// ErrorClasser propogates an error's class.
	ErrorClasser interface {
		OTErrorClass() string
	}

	// ErrorAttributer propogates an error's attributes.
	ErrorAttributer interface {
		OTErrorAttributes() []attribute.KeyValue
	}
)

Optionally, additionally provide the following interface to allow conversion from types that cannot implement the above.

type (
	ErrorConverter interface {
		OpenTelemetryError() error
	}
)

Alternatives

n/a

Prior Art

• github.com/newrelic/go-agent.NoticeError
• grpc/status.FromError

Additional Context

n/a

[MadVikingGod]

For others this issue is referring to Span.RecordError(), which is implemented by the sdk's recordingSpan

I think this might be proposing too much. We could probably pare it down to just one interface:

type ErrorWithAttributes interface {
    OTELAttributes() []attribute.KeyValue
}

The reason is that the other interfaces you've defined are just specialized versions of this one.

I think it could be a workable solution, but I think that the use cases need to be expanded a bit more. The other thing is where would this live? If it was only defined in the SDK, then its discovery is minimized and it will likely add unneeded dependencies on the SDK (libraries shouldn't need to depend on the SDK). If we put it in the API then I think this needs more thought of how to minimize impact.

[tmc]

I'd define that type more generically:

type AttributeProvider interface {
    Attributes() []attribute.KeyValue
}

That said I think a more direct manner of allowing Errors to define the value for the exception.type

semconv.ExceptionType currently calls typeStr: https://github.com/open-telemetry/opentelemetry-go/blob/main/sdk/trace/span.go#L458

Which supplies no way to give a value.

A simple solution to this would be:

type ExceptionTyper interface {
    ExceptionType() string
}

[pellared]

There is a (long term) plan to deprecate RecordError in favor of recording exceptions via Logs API.
References:

• OTEP: Span Event API deprecation plan
• instrumentation: update error handling to set attributes instead of recording errors opentelemetry-go-contrib#8386
• Update exception recording guidelines to not use span events semantic-conventions#3256
• [DO NOT MERGE] [Trace] Deprecate Record Exception API in favor of using Logs API opentelemetry-specification#4825

I do not think we should invest more in RecordError. Therefore, I am closing this issue.