Ecostack commented on code in PR #104:
URL: https://github.com/apache/skywalking-go/pull/104#discussion_r1360360058
##########
docs/en/advanced-features/manual-apis/toolkit-trace.md:
##########
@@ -0,0 +1,124 @@
+# Tracing APIs
+
+## Add trace Toolkit
+
+toolkit/trace provides the APIs to enhance the trace context, such as
createLocalSpan, createExitSpan, createEntrySpan, log, tag, prepareForAsync and
asyncFinish.
+Add the toolkit dependency to your project.
+
+```go
+import "github.com/apache/skywalking-go/toolkit/trace"
+```
+
+## Use Native Tracing
+
+### Context Carrier
+
+The context carrier is used to pass the context between the difference
application.
+
+When creating an Entry Span, you need to obtain the context carrier from the
request. When creating an Exit Span, you need to write the context carrier into
the target RPC request.
+
+```go
+type ExtractorRef func(headerKey string) (string, error)
+
+type InjectorRef func(headerKey, headerValue string) error
+```
+
+### Create Span
+
+Use `trace.CreateEntrySpan()` API to create entry span, and then use `SpanRef`
to contain the reference of created span in agent kernel.
+
+- The first parameter is operation name of span
+- the second parameter is `InjectorRef`.
+
+```go
+spanRef, err := trace.CreateEntrySpan("operationName", InjectorRef)
+```
+
+Use `trace.CreateLocalSpan()` API to create local span
+
+- the only parameter is the operation name of span.
+
+```go
+spanRef, err := trace.CreateLocalSpan("operationName")
+```
+
+Use `trace.CreateExitSpan()` API to create exit span.
+
+- the first parameter is the operation name of span
+- the second parameter is the remote peer which means the peer address of exit
operation.
+- the third parameter is the `ExtractorRef`
+
+```go
+spanRef, err := trace.CreateExitSpan("operationName", "peer", ExtractorRef)
+```
+
+Use `trace.StopSpan()` API to stop current span
+
+```go
+trace.StopSpan()
+```
+
+### Add Span’s Tag and Log
+
+Use `trace.SetLog` to record log in span.
+
+Use `trace.SetTag` to add tag to span, the parameters of tag are two String
which are key and value respectively.
+
+```go
+trace.SetLog(...string)
+
+trace.SetTag("key","value")
+```
+
+### Async Prepare/Finish
+
+Use `trace.PrepareAsync()` to make current span still alive until
`trace.AsyncFinish()` called.
Review Comment:
Maybe trace.PrepareAsync and trace.AsyncFinish could be aligned in the word
order. I am not sure how the other functions are named but how about renaming
trace.AsyncFinish to trace.FinishAsync?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
