This is an automated email from the ASF dual-hosted git repository. kezhenxu94 pushed a commit to branch events in repository https://gitbox.apache.org/repos/asf/skywalking.git
commit 845312f28b61bf51beba5a3205dd04e38c0ae08b Author: kezhenxu94 <[email protected]> AuthorDate: Tue Jan 12 16:17:14 2021 +0800 Draft the doc of event concept --- docs/en/concepts-and-designs/README.md | 2 ++ docs/en/concepts-and-designs/event.md | 53 ++++++++++++++++++++++++++++++++++ 2 files changed, 55 insertions(+) diff --git a/docs/en/concepts-and-designs/README.md b/docs/en/concepts-and-designs/README.md index f04a7b0..e0a98b1 100644 --- a/docs/en/concepts-and-designs/README.md +++ b/docs/en/concepts-and-designs/README.md @@ -23,3 +23,5 @@ SkyWalking already support. - [Overview](ui-overview.md). A simple brief about SkyWalking UI. - CLI - [SkyWalking CLI](https://github.com/apache/skywalking-cli). A command line interface for SkyWalking. +- Events + - [Events](event.md). Introduce the concept of "Event" in SkyWalking. diff --git a/docs/en/concepts-and-designs/event.md b/docs/en/concepts-and-designs/event.md new file mode 100644 index 0000000..5693f72 --- /dev/null +++ b/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.
