Time units are underdocumented in the API

[elisw93]

Describe your environment

(not relevant)

What happened?

It is noted in the OpenTracing shim documentation that OTel internally uses an int of nanoseconds since epoch to represent time values:

https://github.com/open-telemetry/opentelemetry-python/blob/0c9c624327cddf046f1170add4818b805b7b7b30/shim/opentelemetry-opentracing-shim/src/opentelemetry/shim/opentracing_shim/init.py#L53-L59

However, the units are not described when working with time values in the API.

Steps to Reproduce

I will list the examples that I know of:

opentelemetry.trace.Tracer.start_span and opentelemetry.trace.Tracer.start_as_current_span:

https://github.com/open-telemetry/opentelemetry-python/blob/0c9c624327cddf046f1170add4818b805b7b7b30/opentelemetry-api/src/opentelemetry/trace/init.py#L327

https://github.com/open-telemetry/opentelemetry-python/blob/0c9c624327cddf046f1170add4818b805b7b7b30/opentelemetry-api/src/opentelemetry/trace/init.py#L400

opentelemetry.trace.span.Span.end: (this also fails to document the end_time argument)

https://github.com/open-telemetry/opentelemetry-python/blob/0c9c624327cddf046f1170add4818b805b7b7b30/opentelemetry-api/src/opentelemetry/trace/span.py#L62-L64

Expected Result

I would expect to understand how my time values ought to be represented by reading the API documentation.

Actual Result

The relevant units are not mentioned in the documentation and I must find out about them by other means (reading other parts of the documentation; searching on Stack Overflow; etc.)

Additional context

I have considered the possibility that these units are left intentionally unspecified in order that subclasses of Tracer and Span might be free to use their own representation of time. However, in this case I don't understand the motivation of requiring that this type must be int.

Would you like to implement a fix?

Yes

[elisw93]

Could I get an update on this bug? Is there any additional information I should provide? I can update the documentation myself, but I was hoping to get an acknowledgement from the maintainer that the documentation is indeed lacking here and should be improved.

[xrmx]

I guess the type is int because the sdk is using time_ns output as value by default.

[elisw93]

@xrmx

I guess the type is int because the sdk is using time_ns output as value by default.

In that case, is it appropriate to defer to the documentation for the return value of time.time_ns() in the Python SDK?

...returns time as an integer number of nanoseconds since the epoch.

where:

The epoch is the point where the time starts, the return value of time.gmtime(0). It is January 1, 1970, 00:00:00 (UTC) on all platforms.