This is an automated email from the ASF dual-hosted git repository.
wusheng pushed a commit to branch master
in repository
https://gitbox.apache.org/repos/asf/skywalking-data-collect-protocol.git
The following commit(s) were added to refs/heads/master by this push:
new 577656b Add more comments for the protocol.
577656b is described below
commit 577656bc52aaf0471c9f241c6a19b337937827df
Author: Wu Sheng <[email protected]>
AuthorDate: Wed Aug 5 17:08:56 2020 +0800
Add more comments for the protocol.
---
language-agent/JVMMetric.proto | 1 +
language-agent/Tracing.proto | 106 ++++++++++++++++++++++++++++++++++
management/Management.proto | 5 ++
service-mesh-probe/service-mesh.proto | 5 ++
4 files changed, 117 insertions(+)
diff --git a/language-agent/JVMMetric.proto b/language-agent/JVMMetric.proto
index cf3587d..0de1477 100644
--- a/language-agent/JVMMetric.proto
+++ b/language-agent/JVMMetric.proto
@@ -25,6 +25,7 @@ option go_package = "skywalking/network/language/agent/v3";
import "common/Common.proto";
+// Define the JVM metrics report service.
service JVMMetricReportService {
rpc collect (JVMMetricCollection) returns (Commands) {
}
diff --git a/language-agent/Tracing.proto b/language-agent/Tracing.proto
index 9ff9587..a8142b3 100644
--- a/language-agent/Tracing.proto
+++ b/language-agent/Tracing.proto
@@ -25,73 +25,179 @@ option go_package = "skywalking/network/language/agent/v3";
import "common/Common.proto";
+// Define a trace segment report service.
+// All language agents or any trace collecting component, could use this
service to send span collection to the SkyWalking OAP backend.
service TraceSegmentReportService {
rpc collect (stream SegmentObject) returns (Commands) {
}
}
+// The segment is a collection of spans. It includes all collected spans in a
simple one request context, such as a HTTP request process.
+//
+// We recommend the agent/SDK report all tracked data of one request once for
all, such as,
+// typically, such as in Java, one segment represent all tracked
operations(spans) of one request context in the same thread.
+// At the same time, in some language there is not a clear concept like
golang, it could represent all tracked operations of one request context.
message SegmentObject {
+ // A string id represents the whole trace.
string traceId = 1;
+ // A unique id represents this segment. Other segments could use this id
to reference as a child segment.
string traceSegmentId = 2;
+ // Span collections included in this segment.
repeated SpanObject spans = 3;
+ // **Service**. Represents a set/group of workloads which provide the same
behaviours for incoming requests.
+ //
+ // The logic name represents the service. This would show as a separate
node in the topology.
+ // The metrics analyzed from the spans, would be aggregated for this
entity as the service level.
string service = 4;
+ // **Service Instance**. Each individual workload in the Service group is
known as an instance. Like `pods` in Kubernetes, it
+ // doesn't need to be a single OS process, however, if you are using
instrument agents, an instance is actually a real OS process.
+ //
+ // The logic name represents the service instance. This would show as a
separate node in the instance relationship.
+ // The metrics analyzed from the spans, would be aggregated for this
entity as the service instance level.
string serviceInstance = 5;
+ // Whether the segment includes all tracked spans.
+ // In the production environment tracked, some tasks could include too
many spans for one request context, such as a batch update for a cache, or an
async job.
+ // The agent/SDK could optimize or ignore some tracked spans for better
performance.
+ // In this case, the value should be flagged as TRUE.
bool isSizeLimited = 6;
}
+// Segment reference represents the link between two existing segment.
message SegmentReference {
+ // Represent the reference type. It could be across thread or across
process.
+ // Across process means there is a downstream RPC call for this.
+ // Typically, refType == CrossProcess means SpanObject#spanType = entry.
RefType refType = 1;
+ // A string id represents the whole trace.
string traceId = 2;
+ // Another segment id as the parent.
string parentTraceSegmentId = 3;
+ // The span id in the parent trace segment.
int32 parentSpanId = 4;
+ // The service logic name of the parent segment.
+ // If refType == CrossThread, this name is as same as the trace segment.
string parentService = 5;
+ // The service logic name instance of the parent segment.
+ // If refType == CrossThread, this name is as same as the trace segment.
string parentServiceInstance = 6;
+ // The endpoint name of the parent segment.
+ // **Endpoint**. A path in a service for incoming requests, such as an
HTTP URI path or a gRPC service class + method signature.
+ // In a trace segment, the endpoint name is the name of first entry span.
string parentEndpoint = 7;
+ // The network address, including ip/hostname and port, which is used in
the client side.
+ // Such as Client --> use 127.0.11.8:913 -> Server
+ // then, in the reference of entry span reported by Server, the value of
this field is 127.0.11.8:913.
+ // This plays the important role in the SkyWalking STAM(Streaming Topology
Analysis Method)
+ // For more details, read https://wu-sheng.github.io/STAM/
string networkAddressUsedAtPeer = 8;
}
+// Span represents a execution unit in the system, with duration and many
other attributes.
+// Span could be a method, a RPC, MQ message produce or consume.
+// In the practice, the span should be added when it is really necessary, to
avoid payload overhead.
+// We recommend to creating spans in across process(client/server of RPC/MQ)
and across thread cases only.
message SpanObject {
+ // The number id of the span. Should be unique in the whole segment.
+ // Starting at 0.
int32 spanId = 1;
+ // The number id of the parent span in the whole segment.
+ // -1 represents no parent span.
+ // Also, be known as the root/first span of the segment.
int32 parentSpanId = 2;
+ // Start timestamp in milliseconds of this span,
+ // measured between the current time and midnight, January 1, 1970 UTC.
int64 startTime = 3;
+ // End timestamp in milliseconds of this span,
+ // measured between the current time and midnight, January 1, 1970 UTC.
int64 endTime = 4;
+ // <Optional>
+ // In the across thread and across process, these references targeting the
parent segments.
+ // The references usually have only one element, but in batch consumer
case, such as in MQ or async batch process, it could be multiple.
repeated SegmentReference refs = 5;
+ // A logic name represents this span.
+ //
+ // We don't recommend to include the parameter, such as HTTP request
parameters, as a part of the operation, especially this is the name of the
entry span.
+ // All statistic for the endpoints are aggregated base on this name. Those
parameters should be added in the tags if necessary.
+ // If in some cases, it have to be a part of the operation name,
+ // users should use the Group Parameterized Endpoints capability at the
backend to get the meaningful metrics.
+ // Read
https://github.com/apache/skywalking/blob/master/docs/en/setup/backend/endpoint-grouping-rules.md
string operationName = 6;
+ // Remote address of the peer in RPC/MQ case.
+ // This is required when spanType = Exit, as it is a part of the
SkyWalking STAM(Streaming Topology Analysis Method).
+ // For more details, read https://wu-sheng.github.io/STAM/
string peer = 7;
+ // Span type represents the role in the RPC context.
SpanType spanType = 8;
+ // Span layer represent the component tech stack, related to the network
tech.
SpanLayer spanLayer = 9;
+ // Component id is a predefinited number id in the SkyWalking.
+ // It represents the framework, tech stack used by this tracked span, such
as Spring.
+ // All IDs are defined in the
https://github.com/apache/skywalking/blob/master/oap-server/server-bootstrap/src/main/resources/component-libraries.yml
+ // Send a pull request if you want to add languages, components or mapping
defintions,
+ // all public components could be accepted.
+ // Follow this doc for more details,
https://github.com/apache/skywalking/blob/master/docs/en/guides/Component-library-settings.md
int32 componentId = 10;
+ // The status of the span. False means the tracked execution ends in the
unexpected status.
+ // This affects the successful rate statistic in the backend.
+ // Exception or error code happened in the tracked process doesn't mean
isError == true, the implementations of agent plugin and tracing SDK make the
final decision.
bool isError = 11;
+ // String key, String value pair.
+ // Tags provides more informance, includes parameters.
repeated KeyStringValuePair tags = 12;
+ // String key, String value pair with an accurate timestamp.
+ // Logging some events happening in the context of the span duration.
repeated Log logs = 13;
+ // Force the backend don't do analysis, if the value is TRUE.
+ // The backend has its own configurations to follow or override this.
+ //
+ // Use this mostly because the agent/SDK could know more context of the
service role.
bool skipAnalysis = 14;
}
message Log {
+ // The timestamp in milliseconds of this event.,
+ // measured between the current time and midnight, January 1, 1970 UTC.
int64 time = 1;
+ // String key, String value pair.
repeated KeyStringValuePair data = 2;
}
+// Map to the type of span
enum SpanType {
+ // Server side of RPC. Consumer side of MQ.
Entry = 0;
+ // Client side of RPC. Producer side of MQ.
Exit = 1;
+ // A common local code execution.
Local = 2;
}
+// A ID could be represented by multiple string sections.
message ID {
repeated string id = 1;
}
+// Type of the reference
enum RefType {
+ // Map to the reference targeting the segment in another OS process.
CrossProcess = 0;
+ // Map to the reference targeting the segment in the same process of the
current one, just across thread.
+ // This is only used when the coding language has the thread concept.
CrossThread = 1;
}
+// Map to the layer of span
enum SpanLayer {
+ // Unknown layer. Could be anything.
Unknown = 0;
+ // A database layer, used in tracing the database client component.
Database = 1;
+ // A RPC layer, used in both client and server sides of RPC component.
RPCFramework = 2;
+ // HTTP is a more specific RPCFramework.
Http = 3;
+ // A MQ layer, used in both producer and consuer sides of the MQ component.
MQ = 4;
+ // A cache layer, used in tracing the cache client component.
Cache = 5;
}
\ No newline at end of file
diff --git a/management/Management.proto b/management/Management.proto
index be61478..9589ba4 100644
--- a/management/Management.proto
+++ b/management/Management.proto
@@ -25,10 +25,15 @@ option go_package = "skywalking/network/management/v3";
import "common/Common.proto";
+// Define the service reporting the extra information of the instance.
service ManagementService {
+ // Report custom properties of a service instance.
rpc reportInstanceProperties (InstanceProperties) returns (Commands) {
}
+ // Keep the instance alive in the backend analysis.
+ // Only recommend to do separate keepAlive report when no trace and
metrics needs to be reported.
+ // Otherwise, it is duplicated.
rpc keepAlive (InstancePingPkg) returns (Commands) {
}
diff --git a/service-mesh-probe/service-mesh.proto
b/service-mesh-probe/service-mesh.proto
index 4cdc18f..b54ff95 100644
--- a/service-mesh-probe/service-mesh.proto
+++ b/service-mesh-probe/service-mesh.proto
@@ -25,13 +25,18 @@ option go_package = "skywalking/network/servicemesh/v3";
import "common/Common.proto";
+// Define metrics report service. The metrics format is typically representing
the data model collected in the service mesh case.
service ServiceMeshMetricService {
rpc collect(stream ServiceMeshMetric) returns (MeshProbeDownstream) {
}
}
message ServiceMeshMetric {
+ // Start timestamp in milliseconds of this RPC,
+ // measured between the current time and midnight, January 1, 1970 UTC.
int64 startTime = 1;
+ // End timestamp in milliseconds of this RPC,
+ // measured between the current time and midnight, January 1, 1970 UTC.
int64 endTime = 2;
string sourceServiceName = 3;
string sourceServiceInstance = 4;
