Add more comments for the protocol.

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) {
     }

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

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) {
 
     }

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;