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