Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add ObservedTimestamp to the Log Data Model #2184

Merged
merged 3 commits into from
Dec 10, 2021

Conversation

tigrannajaryan
Copy link
Member

@tigrannajaryan tigrannajaryan commented Dec 2, 2021

Resolves #1875

See the issue above for the detailed discussion. A summary here:

Currently, logs data model describes a single (optional) Timestamp field which describes when the event occurred

Unlike for e.g. spans, there are at least three ways a log record can have timestamp associated:

  1. It can be set by a library supporting OTLP natively
  2. It can be parsed out from the log Body or Attributes (e.g. using timestamp operator for filelogreceiver)
  3. It can be set to receipt timestamp (which is a good fallback when the others are not available or fail)

While the first two can be considered mutually exclusive (if the record had timestamp already assigned, it does not make much sense to attempt parsing log body for it), this is not true with the last one. However, there's only one field where all of them can fit.

This brings several problems, such as:

  • Inability to fallback to receipt timestamp when parsing yielded incorrect value (also, no easy ability to find records with potential timestamp parsing errors)
  • No way to to tell using what method the timestamp was assigned to the record
  • Lack of data to measure delay between log occurrence and log being collected

E.g. currently filelogreceiver sets Timestamp to receipt time - by default, or parsed timestamp - when timestamp operator is used. This makes it impossible to tell later if the log timestamp was parsed or not.

Proposed solution

This adds another field to the log record which would store the receipt timestamp (ObservedTimestamp). It is filled in the record when OpenTelemetry first observes the log record.

See also the clarification about the Timestamp field here #2183

The net result is that we are aiming for 2 timestamp fields like this:

  • Timestamp - Time when the event occurred measured by the origin clock, i.e. the time at the source. This field is optional, it may be missing if the source timestamp is unknown.
  • ObservedTimestamp - Time when the event was observed by the collection system. For events that originate in OpenTelemetry this timestamp is typically set at the generation time and is equal to Timestamp. For events originating externally and collected by OpenTelemetry (e.g. using Collector) this is the time when any of OpenTelemetry's code observed the event measure by the clock of the OpenTelemetry code. This field SHOULD be set once the event is observed by OpenTelemetry.

@tigrannajaryan
Copy link
Member Author

@pmm-sumo @djaglowski please review.

specification/logs/data-model.md Outdated Show resolved Hide resolved
@tigrannajaryan
Copy link
Member Author

@open-telemetry/specs-approvers please review.

@arminru arminru added area:data-model For issues related to data model spec:logs Related to the specification/logs directory labels Dec 7, 2021
Resolves open-telemetry#1875

See the issue for the discussion and the description of the source vs observed timestamps.
@jmacd jmacd enabled auto-merge (squash) December 10, 2021 21:12
@jmacd jmacd merged commit 375388e into open-telemetry:main Dec 10, 2021
@tigrannajaryan tigrannajaryan deleted the add-log-observedtimestamp branch December 10, 2021 22:11
tigrannajaryan added a commit to tigrannajaryan/opentelemetry-proto that referenced this pull request Jan 7, 2022
This implements the log data model specification change open-telemetry/opentelemetry-specification#2184
tigrannajaryan added a commit to tigrannajaryan/opentelemetry-proto that referenced this pull request Jan 7, 2022
This implements the log data model specification change open-telemetry/opentelemetry-specification#2184
tigrannajaryan added a commit to tigrannajaryan/opentelemetry-proto that referenced this pull request Feb 8, 2022
This implements the log data model specification change open-telemetry/opentelemetry-specification#2184
tigrannajaryan added a commit to open-telemetry/opentelemetry-proto that referenced this pull request Feb 9, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area:data-model For issues related to data model spec:logs Related to the specification/logs directory
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Log record receipt timestamp
10 participants