[GitHub] [skywalking] BFergerson commented on a change in pull request #6183: Draft the doc of event concept

[GitBox <gi...@apache.org>]

BFergerson commented on a change in pull request #6183:
URL: https://github.com/apache/skywalking/pull/6183#discussion_r555922170



##########
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.

Review comment:
       ```suggestion
   This doc covers the design of how SkyWalking collects events and what events look like in SkyWalking.
   ```

##########
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.

Review comment:
       ```suggestion
   In reality, a production system experiences many other events that may affect the performance of the system, such as upgrading, rebooting, chaos testing, etc.
   ```

##########
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,

Review comment:
       ```suggestion
   The type of the event. This field is friendly for UI visualization, where events of type `Normal` are considered as normal operations,
   ```

##########
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.

Review comment:
       ```suggestion
   Although some of these events are reflected in the logs, there are many other events that can not. Hence, SkyWalking provides a more native way to collect these events.
   ```

##########
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.

Review comment:
       ```suggestion
   while `Error` are considered as unexpected operations, such as `Crash` events, therefore we can mark them with different colors to be easier identified.
   ```

##########
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.
+
+### Start Time
+
+The start time of the event. This field is mandatory when an event is reported.
+
+### End Time
+
+The end time of the event. This field may be empty if the event has not stopped yet, otherwise it should be a valid timestamp after `startTime`.
+
+**NOTE:** When reporting an event, you typically call the report function twice, one for starting of the event and the other one for ending of the event, with the same UUID.
+There are also cases where you have both the start time and end time already, for example, when exporting events from a 3rd-party system, the start time and end time are already known so that you can
+call the report function only once.

Review comment:
       ```suggestion
   There are also cases where you have both the start time and end time already, for example, when exporting events from a 3rd-party system, the start time and end time are already known so that you can call the report function only once.
   ```

##########
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.

Review comment:
       ```suggestion
   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 SkyWalking.
   ```

##########
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:
       Without this, there should be some mechanism to assign meta information to an event. `message` is good for user-friendly display but events should have the ability to assign more technical error codes as well.




----------------------------------------------------------------
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:
users@infra.apache.org