# Trace Data Protocol v2
Trace Data Protocol describes the data format between SkyWalking agent/sniffer and backend. 

## Overview
Trace data protocol is defined and provided in [gRPC format](https://github.com/apache/skywalking-data-collect-protocol).

For each agent/SDK, it needs to register service id and service instance id before reporting any kind of trace 
or metrics data.

Since SkyWalking v7.x, SkyWalking provided register and uplink trace data through HTTP API way.
[HTTP API Protocol](HTTP-API-Protocol.md) defined the API data format.

### Step 1. Do register
[Register service](https://github.com/apache/skywalking-data-collect-protocol/tree/master/register/Register.proto) takes charge of 
all register methods. At step 1, we need `doServiceRegister`, then `doServiceInstanceRegister`.

1. First of all, do `doServiceRegister`, input is **serviceName**, which could be declared by any UTF-8 String. The return 
value is KeyValue pair, **serviceName** as key, **service id** as value. Batch is also supported.
1. After have **service id**, use `doServiceInstanceRegister` to do instance register. Input is **service id**, **UUID**,
and **register time**. UUID should be unique in the whole distributed environments. The return value is still KeyValue pair,
**UUID** as key, **service instance id** as value. Batch is also supported.

For register, the most important notice is that, the process is expected as async in backend, so, the return could be **NULL**.
In most cases, you need to set a timer to call these services repeated, until you got the response. Suggestion loop cycle, 10s.

Because batch is supported, even for most language agent/SDK, no scenario to do batch register. We suggest to check the  `serviceName`
and `UUID` in response, and match with your expected value.

### Step 2. Send trace and metrics
After you have service id and service instance id, you could send traces and metrics. Now we
have 
1. `TraceSegmentReportService#collect` for skywalking native trace format
1. `JVMMetricReportService#collect` for skywalking native jvm format

For trace format, there are some notices
1. Segment is a concept in SkyWalking, it should include all span for per request in a single OS process, usually single thread based on language.
2. Span has 3 different groups.

* EntrySpan
EntrySpan represents a service provider, also the endpoint of server side. As an APM system, we are targeting the 
application servers. So almost all the services and MQ-consumer are EntrySpan(s).

* LocalSpan
LocalSpan represents a normal Java method, which don't relate with remote service, neither a MQ producer/consumer
nor a service(e.g. HTTP service) provider/consumer.

* ExitSpan
ExitSpan represents a client of service or MQ-producer, as named as `LeafSpan` at early age of SkyWalking.
e.g. accessing DB by JDBC, reading Redis/Memcached are cataloged an ExitSpan. 

3. Span parent info called Reference, which is included in span. Reference carries more fields besides 
trace id, parent segment id, span id. Others are **entry service instance id**, **parent service instance id**,
**entry endpoint**, **parent endpoint** and **network address**. Follow [Cross Process Propagation Headers Protocol v2](Skywalking-Cross-Process-Propagation-Headers-Protocol-v2.md),
you will know how to get all these fields.

4. `segment` in Upstream is the byte array of TraceSegmentObject.

### Step 3. Keep alive.
`ServiceInstancePing#doPing` should be called per several seconds. Make the backend know this instance is still
alive. Existed **service instance id** and **UUID** used in `doServiceInstanceRegister` are required.