Skip to content

Commit

Permalink
Address PR comments
Browse files Browse the repository at this point in the history
  • Loading branch information
Tigran Najaryan committed Aug 14, 2020
1 parent 276a395 commit f014f61
Show file tree
Hide file tree
Showing 2 changed files with 50 additions and 7 deletions.
16 changes: 9 additions & 7 deletions specification/common/common.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ Attribute names SHOULD follow these rules:
words by underscores (i.e. use snake_case). For example `http.status_code`
denotes the status code in the http namespace.

- Attribute names should not coincide with namespaces. For example if
- Attribute names SHOULD NOT coincide with namespaces. For example if
`service.instance.id` is an attribute name then it is no longer valid to have
an attribute named `service.instance` because `service.instance` is already a
namespace. Because of this rule be careful when choosing attribute names:
Expand All @@ -66,7 +66,7 @@ Attribute names SHOULD follow these rules:

#### Recommendations for OpenTelemetry Authors

- All attributes names that are part of OpenTelemetry semantic conventions
- All attribute names that are part of OpenTelemetry semantic conventions
SHOULD be part of a namespace.

- When coming up with a new convention make sure to check existing namespaces
Expand All @@ -80,10 +80,11 @@ Attribute names SHOULD follow these rules:
- When a new namespace is necessary consider whether it should be a top-level
namespace (e.g. `service`) or a nested namespace (e.g. `service.instance`).

- Semantic conventions MUST limit attribute names to
- Semantic conventions MUST limit attribute names to printable Basic Latin
characters (more precisely to
[U+0021 .. U+007E](https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)#Table_of_characters)
subset of Unicode code points only. It is recommended to further limit
attribute names to the following Unicode code points: Latin alphabet, Numeric,
subset of Unicode code points). It is recommended to further limit attribute
names to the following Unicode code points: Latin alphabet, Numeric,
Underscore, Dot (as namespace delimiter).

#### Recommendations for Application Developers
Expand All @@ -108,9 +109,10 @@ new name. To do that consider a few options:
does not clash with an existing semantic convention namespace. If in doubt
prefix it with your company's reverse domain name.

- It is recommended to limit attribute names to
- It is recommended to limit attribute names to printable Basic Latin characters
(more precisely to
[U+0021 .. U+007E](https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)#Table_of_characters)
subset of Unicode code points only.
subset of Unicode code points).

- The attribute may be generally applicable to applications in the industry. In
that case consider submitting a proposal to this specification to add a new
Expand Down
41 changes: 41 additions & 0 deletions specification/logs/events-and-logs.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# Events and Logs

Let’s start with Wikipedia’s definition of log file:

> In computing, a log file is a file that records either events that occur in an
> operating system or other software runs.
The notion of a log record used throughout this document is fully aligned with
Wikipedia’s definition. In fact we claim that in the observability realm there
is no important distinction between logs and recorded events from a data
modeling perspective. Logs are simply records of events.

Logs and Events are different names for the same concept.

Some products may want to make a distinction between Events collected from
certain sources and Logs collected from other sources. We claim that there is
nothing inherently different between logs and events, the differences are in the
sources themselves. Thus where it matters the products should make that
distinction based on the source of the data rather than attempt to arbitrarily
categorize the data as events vs logs.

One traditional way events and logs were thought to be different was that logs
are unstructured while events are structured. This is however an orthogonal
argument, which also contradicts with the fact that there are logging formats
that support structured data and there are modern logging libraries that by
default output structured data rather than unstructured text.

Debates and comments are welcome on this topic. We would like to either confirm
our claim or find definitive arguments in favour of treating events and logs as
different data types.

Additional historical references using the term "logs" in the "events records"
sense:

- From Syslog [RFC5424](https://tools.ietf.org/html/rfc5424): "This document
describes the syslog protocol, which is used to convey **event** notification
**messages**."

- System logs on Windows operating system are known as Windows **Event** Log
(see
[MSDN](https://docs.microsoft.com/en-us/windows/win32/wes/windows-event-log)).

0 comments on commit f014f61

Please sign in to comment.