kezhenxu94 commented on a change in pull request #6183:
URL: https://github.com/apache/skywalking/pull/6183#discussion_r556374825
##########
File path: docs/en/concepts-and-designs/event.md
##########
@@ -0,0 +1,53 @@
+# Events
+
+SkyWalking already supports the three pillars of observability, namely logs,
metrics, and traces.
+While in a production system in reality, there are many other events that may
affect the performance of the system, such as upgrading, rebooting, chaos
testing, etc.
+Although some of these events can reflect from the logs, there are also many
other events that can not, hence SkyWalking provides a more native way to
collect these events.
+This doc covers the design of how the SkyWalking collect events and what
events look lik in SkyWalking.
+
+## How to Report Events
+
+SkyWalking backend supports three protocols to collect events, gRPC, HTTP, and
Kafka. Any agent or CLI that implements one of these protocols can report
events to the SkyWalking.
+Currently, the officially supported clients to report events are:
+
+- [ ] Java Agent Toolkit: Use the Java agent toolkit to report events from
inside the applications.
+- [ ] SkyWalking CLI: Use the CLI to report events from the command line
interface.
+- [ ] Kubernetes Event Exporter: Deploy an event exporter to refine and report
Kubernetes events.
+
+## Event Definition
+
+An event contains the following fields. The definitions of event can be found
at the [protocol repo](#TODO)
+
+### UUID
+
+Unique ID of the event. Because an event may span a long period of time, the
UUID is necessary to associate the start time with the end time of the same
event.
+
+### Object
+
+The object that the event occurs on. In the concepts of SkyWalking, the object
is typically service, service instance, etc.
+
+### Name
+
+The name of the event. For example, `Start`, `Stop`, `Crash`, `Reboot`,
`Upgrade` etc.
+
+### Type
+
+The type of the event. This field is friendly for UI visualization, where
events of type `Normal` is considered as normal operations,
+while `Error` is considered as unexpected operations, such as `Crash` events,
therefore we can mark them with different colors to be easier identified.
+
+### Message
+
+The detail of the event that describes why this event happened. This should be
a one-line message that briefly describes why the event is reported. Examples
of a `Crash` event may be something like `Run out of memory`.
+It's NOT encouraged to include the detailed logs of this event, such as the
exception stack trace.
Review comment:
> I just don't see how you do that with something as simple as `Run out
of memory`. That's good for a summary but IMO it would be nice to have the
ability to attribute additional information. I don't mind if it's through some
JSON field, meta-map, etc.
Having a JSON / meta-map field sounds good to me, but because we don't have
static typings for that field, users are free to report random text of that
JSON / meta-map field.
I'm also wondering how will the structured field be used. There are many
events (some may be unknown for now), whose JSON field properties are
indeterministic.
If we want to provide a JSON field, we may need to list (recommended)
properties of the JSON field for some common events, right?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
