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:

opentelemetry-python/shim/opentelemetry-opentracing-shim/src/opentelemetry/shim/opentracing_shim/__init__.py

Lines 53 to 59 in 0c9c624

	Note:
	While the OpenTracing Python API represents time values as the number of
	**seconds** since the epoch expressed as :obj:`float` values, the
	OpenTelemetry Python API represents time values as the number of
	**nanoseconds** since the epoch expressed as :obj:`int` values. This fact
	requires the OpenTracing shim to convert time values back and forth between
	the two representations, which involves floating point arithmetic.

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:

opentelemetry-python/opentelemetry-api/src/opentelemetry/trace/__init__.py

Line 327 in 0c9c624

start_time: Sets the start time of a span

opentelemetry-python/opentelemetry-api/src/opentelemetry/trace/__init__.py

Line 400 in 0c9c624

start_time: Sets the start time of a span

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

opentelemetry-python/opentelemetry-api/src/opentelemetry/trace/span.py

Lines 62 to 64 in 0c9c624

	"""Sets the current time as the span's end time.
	The span's end time is the wall time at which the operation finished.

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