Browser protocol describes the data format between [skywalking-client-js](https://github.com/apache/skywalking-client-js) and backend.
Browser protocol describes the data format between [skywalking-client-js](https://github.com/apache/skywalking-client-js) and the backend.
## Overview
Browser protocol is defined and provided in [gRPC format](https://github.com/apache/skywalking-data-collect-protocol/blob/master/browser/BrowserPerf.proto),
also implemented in [HTTP 1.1](Browser-HTTP-API-Protocol.md)
and also implemented in [HTTP 1.1](Browser-HTTP-API-Protocol.md)
### Send performance data and error log
### Send performance data and error logs
You can send performance data and error logs via the following services:
You can send performance data and error logs using the following services:
1.`BrowserPerfService#collectPerfData` for performance data format.
1.`BrowserPerfService#collectErrorLogs` for error log format.
For error log format, there are some notices
For error log format, note that:
1.`BrowserErrorLog#uniqueId` should be unique in the whole distributed environments.
1.`BrowserErrorLog#uniqueId` should be unique in all distributed environments.
HTTP API Protocol defines the API data format, including api request and response data format.
HTTP API Protocol defines the API data format, including API request and response data format.
They use the HTTP1.1 wrapper of the official [SkyWalking Trace Data Protocol v3](Trace-Data-Protocol-v3.md). Read it for more details.
## Instance Management
Detail information about data format can be found in [Instance Management](https://github.com/apache/skywalking-data-collect-protocol/blob/master/management/Management.proto).
Detailed information about data format can be found in [Instance Management](https://github.com/apache/skywalking-data-collect-protocol/blob/master/management/Management.proto).
- Report service instance properties
...
...
@@ -50,12 +50,12 @@ OutPut:
## Trace Report
Detail information about data format can be found in [Instance Management](https://github.com/apache/skywalking-data-collect-protocol/blob/master/language-agent/Tracing.proto).
There are two ways to report segment data, one segment per request or segment array in the bulk mode.
Detailed information about data format can be found in [Instance Management](https://github.com/apache/skywalking-data-collect-protocol/blob/master/language-agent/Tracing.proto).
There are two ways to report segment data: one segment per request or segment array in bulk mode.
The Cross Process Correlation Headers Protocol is used to transport custom data by leveraging the capability of [Cross Process Propagation Headers Protocol](Skywalking-Cross-Process-Propagation-Headers-Protocol-v3.md).
This is an optional and additional protocol for language tracer implementation. All tracer implementation could consider to implement this.
This is an optional and additional protocol for language tracer implementation. All tracer implementation could consider implementing this.
Cross Process Correlation Header key is `sw8-correlation`. The value is the `encoded(key):encoded(value)` list with elements splitted by `,` such as `base64(string key):base64(string value),base64(string key2):base64(string value2)`.
## Recommendations of language APIs
Recommended implementation in different language API.
## Recommendations for language APIs
The following implementation method is recommended for different language APIs.
1.`TraceContext#putCorrelation` and `TraceContext#getCorrelation` are recommended to write and read the correlation context, with key/value string.
1. The key should be added if it is absent.
1. The later writes should override the previous value.
1. The latter writes should override the previous value.
1. The total number of all keys should be less than 3, and the length of each value should be less than 128 bytes.
1. The context should be propagated as well when tracing context is propagated across threads and processes.
# SkyWalking Cross Process Propagation Headers Protocol
* Version 3.0
SkyWalking is more likely an APM system, rather than the common distributed tracing system.
The Headers are much more complex than them in order to improving analysis performance of OAP.
You can find many similar mechanism in other commercial APM systems. (Some are even much more complex than our's)
SkyWalking is more akin to an APM system, rather than a common distributed tracing system.
SkyWalking's headers are much more complex than those found in a common distributed tracing system. The reason behind their complexity is for better analysis performance of the OAP.
You can find many similar mechanisms in other commercial APM systems (some of which are even more complex than ours!).
## Abstract
SkyWalking Cross Process Propagation Headers Protocol v3 is also named as sw8 protocol, which is for context propagation.
The SkyWalking Cross Process Propagation Headers Protocol v3, also known as the sw8 protocol, is designed for context propagation.
### Standard Header Item
The standard header should be the minimal requirement for the context propagation.
The standard header is the minimal requirement for context propagation.
* Header Name: `sw8`.
* Header Value: 8 fields split by `-`. The length of header value should be less than 2k(default).
* Header Value: 8 fields split by `-`. The length of header value must be less than 2k (default).
Value format example,`XXXXX-XXXXX-XXXX-XXXX`
Example of the value format:`XXXXX-XXXXX-XXXX-XXXX`
#### Values
Values include the following segments, all String type values are in BASE64 encoding.
- Required(s)
1. Sample. 0 or 1. 0 means context exists, but could(most likely will) ignore. 1 means this trace need to be sampled and send to backend.
1. Trace Id. **String(BASE64 encoded)**. Literal String and unique globally.
1. Parent span Id. Integer. Begin with 0. This span id points to the parent span in parent trace segment.
1. Parent service. **String(BASE64 encoded)**. The length should not be less or equal than 50 UTF-8 characters.
1. Parent service instance. **String(BASE64 encoded)**. The length should be less or equal than 50 UTF-8 characters.
1. Parent endpoint. **String(BASE64 encoded)**. Operation Name of the first entry span in the parent segment. The length should be less than 150 UTF-8 characters.
1. Target address used at client side of this request. **String(BASE64 encoded)**. The network address(not must be IP + port) used at client side to access this target
service.
- Sample values,
Values must include the following segments, and all string type values are in BASE64 encoding.
- Required:
1. Sample. 0 or 1. 0 means that the context exists, but it could (and most likely will) be ignored. 1 means this trace needs to be sampled and sent to the backend.
1. Trace ID. **String(BASE64 encoded)**. A literal string that is globally unique.
1. Parent trace segment ID. **String(BASE64 encoded)**. A literal string that is globally unique.
1. Parent span ID. Must be an integer. It begins with 0. This span ID points to the parent span in parent trace segment.
1. Parent service. **String(BASE64 encoded)**. Its length should be no more than 50 UTF-8 characters.
1. Parent service instance. **String(BASE64 encoded)**. Its length should be no more than 50 UTF-8 characters.
1. Parent endpoint. **String(BASE64 encoded)**. The operation name of the first entry span in the parent segment. Its length should be less than 150 UTF-8 characters.
1. Target address of this request used on the client end. **String(BASE64 encoded)**. The network address (not necessarily IP + port) used on the client end to access this target service.
Extension header item is designed for the advanced features. It provides the interaction capabilities between the agents
The extension header item is designed for advanced features. It provides interaction capabilities between the agents
deployed in upstream and downstream services.
* Header Name: `sw8-x`
* Header Value: Split by `-`. The fields are extendable.
#### Values
The current value includes fields.
1. Tracing Mode. empty, 0 or 1. empty or 0 is default. 1 represents all spans generated in this context should skip analysis,
`spanObject#skipAnalysis=true`. This context should be propagated to upstream in the default, unless it is changed in the
1. Tracing Mode. Empty, 0, or 1. Empty or 0 is the default. 1 indicates that all spans generated in this context will skip analysis,
`spanObject#skipAnalysis=true`. This context is propagated to upstream by default, unless it is changed in the
tracing process.
2. The timestamp of sending at the client-side. This is used in async RPC such as MQ. Once it is set, the consumer side would calculate the latency between sending and receiving, and tag the latency in the span by using key `transmission.latency` automatically.
2. The timestamp of sending on the client end. This is used in async RPC, such as MQ. Once it is set, the consumer end would calculate the latency between sending and receiving, and tag the latency in the span by using key `transmission.latency` automatically.
