未验证 提交 76847db7 编写于 作者: W Wing 提交者: GitHub

Refine protocols doc (#8049)

上级 1b8dbd3f
# Probe Protocol # Probe Protocols
It includes descriptions and definitions on how agents send collected metrics, logs, traces and events, as well as the format of each entity. Probe protocols describe and define how agents send collected metrics, logs, traces, and events, as well as set out the format of each entity.
## Probe Protocols
They also related to the probe group. For more information, see [Concepts and Designs](../concepts-and-designs/overview.md).
These groups are **language-based native agent protocol**, **service mesh protocol** and **3rd-party instrument protocol**.
### Tracing ### Tracing
There are two types of protocols that help language agents work in distributed tracing. There are two types of protocols that help language agents work in distributed tracing.
- **Cross Process Propagation Headers Protocol** and **Cross Process Correlation Headers Protocol** come in in-wire data format. Agent/SDK usually uses HTTP/MQ/HTTP2 headers - **Cross Process Propagation Headers Protocol** and **Cross Process Correlation Headers Protocol** come in in-wire data format. Agent/SDK usually uses HTTP/MQ/HTTP2 headers to carry the data with the RPC request. The remote agent will receive this in the request handler, and bind the context with this specific request.
to carry the data with the RPC request. The remote agent will receive this in the request handler, and bind the context with this specific request.
[Cross Process Propagation Headers Protocol v3](Skywalking-Cross-Process-Propagation-Headers-Protocol-v3.md) has been the new protocol for in-wire context propagation since the version 8.0.0 release. [Cross Process Propagation Headers Protocol v3](Skywalking-Cross-Process-Propagation-Headers-Protocol-v3.md) has been the new protocol for in-wire context propagation since the version 8.0.0 release.
...@@ -26,14 +21,14 @@ Please read SkyWalking language agents documentation to see whether it is suppor ...@@ -26,14 +21,14 @@ Please read SkyWalking language agents documentation to see whether it is suppor
### Metrics ### Metrics
SkyWalking has native metrics format, and support widely used metric formats such as Prometheus, OpenCensus, and Zabbix. SkyWalking has a native metrics format, and supports widely used metric formats, such as Prometheus, OpenCensus, and Zabbix.
The native metrics format definition could be found [here](https://github.com/apache/skywalking-data-collect-protocol/blob/master/language-agent/Meter.proto). The native metrics format definition could be found [here](https://github.com/apache/skywalking-data-collect-protocol/blob/master/language-agent/Meter.proto).
Typically, agent meter plugin(e.g. [Java Meter Plugin](https://skywalking.apache.org/docs/skywalking-java/latest/en/setup/service-agent/java-agent/java-plugin-development-guide/#meter-plugin)) and Typically, the agent meter plugin (e.g. [Java Meter Plugin](https://skywalking.apache.org/docs/skywalking-java/latest/en/setup/service-agent/java-agent/java-plugin-development-guide/#meter-plugin)) and
Satellite [Prometheus fetcher](https://skywalking.apache.org/docs/skywalking-satellite/latest/en/setup/plugins/fetcher_prometheus-metrics-fetcher/) Satellite [Prometheus fetcher](https://skywalking.apache.org/docs/skywalking-satellite/latest/en/setup/plugins/fetcher_prometheus-metrics-fetcher/)
would transfer metrics into native format and forward to SkyWalking OAP server. would convert metrics into native format and forward them to SkyWalking OAP server.
About receiving 3rd party formats metrics, read [Meter receiver](../setup/backend/backend-meter.md) and [OpenTelemetry receiver](../setup/backend/opentelemetry-receiver.md) docs for more details. To learn more about receiving 3rd party formats metrics, see [Meter receiver](../setup/backend/backend-meter.md) and [OpenTelemetry receiver](../setup/backend/opentelemetry-receiver.md).
### Browser probe protocol ### Browser probe protocol
...@@ -45,8 +40,8 @@ The browser probe, such as [skywalking-client-js](https://github.com/apache/sky ...@@ -45,8 +40,8 @@ The browser probe, such as [skywalking-client-js](https://github.com/apache/sky
The protocol is used to report events to the backend. The [doc](../concepts-and-designs/event.md) introduces the definition of an event, and [the protocol repository](https://github.com/apache/skywalking-data-collect-protocol/blob/master/event) defines gRPC services and message formats of events. The protocol is used to report events to the backend. The [doc](../concepts-and-designs/event.md) introduces the definition of an event, and [the protocol repository](https://github.com/apache/skywalking-data-collect-protocol/blob/master/event) defines gRPC services and message formats of events.
Report `JSON` format events via HTTP API, the endpoint is `http://<oap-address>:12800/v3/events`. `JSON` format events can be reported via HTTP API. The endpoint is `http://<oap-address>:12800/v3/events`.
JSON event record example: Example of a JSON event record:
```json ```json
[ [
{ {
......
...@@ -2,13 +2,11 @@ ...@@ -2,13 +2,11 @@
Trace Data Protocol describes the data format between SkyWalking agent/sniffer and backend. Trace Data Protocol describes the data format between SkyWalking agent/sniffer and backend.
## Overview ## Overview
Trace data protocol is defined and provided in [gRPC format](https://github.com/apache/skywalking-data-collect-protocol), Trace data protocol is defined and provided in [gRPC format](https://github.com/apache/skywalking-data-collect-protocol), and implemented in [HTTP 1.1](HTTP-API-Protocol.md).
also implemented in [HTTP 1.1](HTTP-API-Protocol.md)
### Report service instance status ### Report service instance status
1. Service Instance Properties 1. Service Instance Properties
Service instance contains more information than just a name. Once the agent wants to report this, use `ManagementService#reportInstanceProperties` service Service instance contains more information than just a name. In order for the agent to report service instance status, use `ManagementService#reportInstanceProperties` service to provide a string-key/string-value pair list as the parameter. The `language` of target instance must be provided as the minimum requirement.
to provide a string-key/string-value pair list as the parameter. `language` of target instance is expected at least.
2. Service Ping 2. Service Ping
Service instance should keep alive with the backend. The agent should set a scheduler using `ManagementService#keepAlive` service every minute. Service instance should keep alive with the backend. The agent should set a scheduler using `ManagementService#keepAlive` service every minute.
...@@ -17,7 +15,7 @@ Service instance should keep alive with the backend. The agent should set a sche ...@@ -17,7 +15,7 @@ Service instance should keep alive with the backend. The agent should set a sche
After you have the service ID and service instance ID ready, you could send traces and metrics. Now we After you have the service ID and service instance ID ready, you could send traces and metrics. Now we
have have
1. `TraceSegmentReportService#collect` for the SkyWalking native trace format 1. `TraceSegmentReportService#collect` for the SkyWalking native trace format
1. `JVMMetricReportService#collect` for the SkyWalking native jvm format 1. `JVMMetricReportService#collect` for the SkyWalking native JVM format
For trace format, note that: For trace format, note that:
1. The segment is a unique concept in SkyWalking. It should include all spans for each request in a single OS process, which is usually a single language-based thread. 1. The segment is a unique concept in SkyWalking. It should include all spans for each request in a single OS process, which is usually a single language-based thread.
......
...@@ -139,10 +139,10 @@ extend type Query { ...@@ -139,10 +139,10 @@ extend type Query {
} }
``` ```
Log implementations have a little differences with different database options. Search engine(s), e.g. ElasticSearch and OpenSearch, could support Log implementations vary between different database options. Some search engines like ElasticSearch and OpenSearch can support
full log text fuzzy query. Others would not support considering performance impact and end user experience. full log text fuzzy queries, while others do not due to considerations related to performance impact and end user experience.
`test` API is provided for the debugger tool of native LAL parsing. `test` API serves as the debugging tool for native LAL parsing.
### Trace ### Trace
```graphql ```graphql
...@@ -152,7 +152,7 @@ extend type Query { ...@@ -152,7 +152,7 @@ extend type Query {
} }
``` ```
Trace query provides to fetch trace segment list, and spans of given trace id. Trace query fetches trace segment lists and spans of given trace IDs.
### Alarm ### Alarm
```graphql ```graphql
...@@ -162,7 +162,7 @@ extend type Query { ...@@ -162,7 +162,7 @@ extend type Query {
} }
``` ```
Alarm query provides to query detected alerting messages with relative events. Alarm query identifies alarms and related events.
### Event ### Event
```graphql ```graphql
...@@ -171,7 +171,7 @@ extend type Query { ...@@ -171,7 +171,7 @@ extend type Query {
} }
``` ```
Event query is fetching the event list according to given sources and time range conditions. Event query fetches the event list based on given sources and time range conditions.
## Condition ## Condition
### Duration ### Duration
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册