Add short page on event data #156
Conversation
… into mano/short-event-data
There was a problem hiding this comment.
I want to see us start with the bigger story of timestamped event data, and then narrow to engineering consciously and clearly in the material. This reads the other way around to me: It starts with conventions and language from the engineering domain, and then tries to work up to a wider play. Based on our conversation, would you be open to trying one more revision? I think there is a great base here!
getting-started-guide/event-data.mdx
Outdated
| sidebarTitle: Events | ||
| --- | ||
|
|
||
| In Axiom, event data is the atomic unit of activity, encompassing logs, traces, and even product interactions. Each event is simply a structured record—composed of key-value pairs—that captures meaningful interactions or changes in state within a system. While these can appear in various forms, from log lines to complex traces, they usually contain the following: |
There was a problem hiding this comment.
Let’s call it "timestamped event data" in the first mention, and event data thereafter. I want to ground event data very clearly in time from the outset. Note: This is not described as time series event data. The language choice is intentional, to distance Axiom rightly from time series DBs.
getting-started-guide/event-data.mdx
Outdated
| sidebarTitle: Events | ||
| --- | ||
|
|
||
| In Axiom, event data is the atomic unit of activity, encompassing logs, traces, and even product interactions. Each event is simply a structured record—composed of key-value pairs—that captures meaningful interactions or changes in state within a system. While these can appear in various forms, from log lines to complex traces, they usually contain the following: |
There was a problem hiding this comment.
In the past, I have said that event data is the record of every interaction between human, sensor, and machine. i can’t remember where that originated from, either cfrln or a deep dive on the history of event data ~Q1/Q2, but the reason I gravitated towards it is because it zooms us out from any use case first, to create an appreciation for the total scope and opportunity before honing in.
By putting logs and traces as the first and second example, it feels to me that we have already coupled Axiom so tightly to engineering use cases, and then we try and walk it back with the third example, product interactions. I really want the reader to feel that timestamped event data is the record of absolutely every digital interactional - the digital breadcrumb - and then (and only then) for us to contextualize that with domain-specific examples. That could work better as two sentences.
getting-started-guide/event-data.mdx
Outdated
| sidebarTitle: Events | ||
| --- | ||
|
|
||
| In Axiom, event data is the atomic unit of activity, encompassing logs, traces, and even product interactions. Each event is simply a structured record—composed of key-value pairs—that captures meaningful interactions or changes in state within a system. While these can appear in various forms, from log lines to complex traces, they usually contain the following: |
There was a problem hiding this comment.
While these can appear in various forms, from log lines to complex traces
Again, I feel the same way as above. This innocuous "from" scopes the breadth of use cases to engineering when I read this. The framing is changed from what I want the world to know, which is that every function in any business with digital activity can and will benefit from Axiom.
getting-started-guide/event-data.mdx
Outdated
|
|
||
| - **Timestamp**: When the event occurred. | ||
| - **Attributes**: A set of key-value pairs offering details about the event context. | ||
| - **Metadata**: Contextual labels and IDs, such as trace ID and span ID, that connect related events. |
There was a problem hiding this comment.
For the avoidance of doubt, I feel the same way here about "such as trace ID and span ID".
getting-started-guide/event-data.mdx
Outdated
| - **Attributes**: A set of key-value pairs offering details about the event context. | ||
| - **Metadata**: Contextual labels and IDs, such as trace ID and span ID, that connect related events. | ||
|
|
||
| Rather than simply calling them logs or metrics, event data reflects a broader range of interactions, crossing boundaries from engineering to product management, security, and beyond. This includes everything from the number of documents created in a product to the sequence of API calls during a checkout process. |
There was a problem hiding this comment.
Good.
"Whole engineers might most often work with timestamped event data in the form of logs or metrics..."
Something like this ^ might be more effective. I don’t love the phrasing, but the goal again would be to say: We know our most common reader is likely to be an engineer because of Axiom’s history, but that there is a bigger opp here for a business.
getting-started-guide/event-data.mdx
Outdated
|
|
||
| Rather than simply calling them logs or metrics, event data reflects a broader range of interactions, crossing boundaries from engineering to product management, security, and beyond. This includes everything from the number of documents created in a product to the sequence of API calls during a checkout process. | ||
|
|
||
| ## Types of event data |
There was a problem hiding this comment.
I know that you want to set up the punchline of Axiom’s metrics compatibility, but the problem here is we have now gone from what I hope will be a world view that timestamped event data shows up everywhere, to narrowing down even more than engineering to observability.
If I look at this page, I would definitely leave thinking Axiom is just another engineering-focused tool. How could we change that perception?
Does it need a heading that shows we are narrowing to the engineering use case specifically? Is this section or mention of observability needed at all?
getting-started-guide/event-data.mdx
Outdated
| - **Traces**: Traces track the path of requests through a system, capturing each step’s duration. By linking related spans within a trace, developers can identify bottlenecks and dependencies. | ||
| - **Metrics**: Metrics quantify state over time, recording data like CPU usage or user count at intervals. Product or engineering teams can then monitor and aggregate these values for performance insights. | ||
|
|
||
| In Axiom, these observability elements are stored as event data, allowing for fine-grained, efficient tracking across all three pillars. |
There was a problem hiding this comment.
"Just like any other type of (timestamped) event data, ..."
There was a problem hiding this comment.
So far mistakenly considered not event data, but in fact also event data
getting-started-guide/event-data.mdx
Outdated
|
|
||
| In Axiom, these observability elements are stored as event data, allowing for fine-grained, efficient tracking across all three pillars. | ||
|
|
||
| ## Metrics support |
There was a problem hiding this comment.
Putting all of the above to one side, yes, this is good. It answers the question of our current metrics status, which is not well covered elsewhere.
|
@dominicchapman I've implemented your suggestions. Most importantly, I've made the distinction clear between the general concept of event data and its particular use cases by splitting the original text into two pages: one about event data in general and its many use cases, and another about observability as a common (but not a singularly important) use case. Looking forward to what you think! |
Preview: