README.md

    GO2Sky

    Build Coverage GoDoc

    GO2Sky is an instrument SDK library, written in Go, by following Apache SkyWalking tracing and metrics formats.

    Installation

    $ go get -u github.com/SkyAPM/go2sky

    The API of this project is still evolving. The use of vendoring tool is recommended.

    Quickstart

    By completing this quickstart, you will learn how to trace local methods. For more details, please view the example.

    Configuration

    GO2Sky can export traces to Apache SkyWalking OAP server or local logger. In the following example, we configure GO2Sky to export to OAP server, which is listening on oap-skywalking port 11800, and all the spans from this program will be associated with a service name example. reporter.GRPCReporter can also adjust the behavior through reporter.GRPCReporterOption, view all.

    r, err := reporter.NewGRPCReporter("oap-skywalking:11800")
    if err != nil {
        log.Fatalf("new reporter error %v \n", err)
    }
    defer r.Close()
    tracer, err := go2sky.NewTracer("example", go2sky.WithReporter(r))

    Create span

    To create a span in a trace, we used the Tracer to start a new span. We indicate this as the root span because of passing context.Background(). We must also be sure to end this span, which will be show in End span.

    span, ctx, err := tracer.CreateLocalSpan(context.Background())

    Get Global TraceID

    Get the TraceID of the activeSpan in the Context.

    go2sky.TraceID(ctx)

    Create a sub span

    A sub span created as the children of root span links to its parent with Context.

    subSpan, newCtx, err := tracer.CreateLocalSpan(ctx)

    End span

    We must end the spans so they becomes available for sending to the backend by a reporter.

    subSpan.End()
    span.End()

    Advanced Concepts

    We cover some advanced topics about GO2Sky.

    Context propagation

    Trace links spans belong to it by using context propagation which varies between different scenario.

    In process

    We use context package to link spans. The root span usually pick context.Background(), and sub spans will inject the context generated by its parent.

    //Create a new context
    entrySpan, entryCtx, err := tracer.CreateEntrySpan(context.Background(), ...)
    
    // Some operation
    ...
    
    // Link two spans by injecting entrySpan context into exitSpan
    exitSpan, err := tracer.CreateExitSpan(entryCtx, ...)

    Crossing process

    We use Entry span to extract context from downstream service, and use Exit span to inject context to upstream service.

    Entry and Exit spans make sense to OAP analysis which generates topology map and service metrics.

    //Extract context from HTTP request header `sw8`
    span, ctx, err := tracer.CreateEntrySpan(r.Context(), "/api/login", func() (string, error) {
    		return r.Header.Get("sw8"), nil
    })
    
    // Some operation
    ...
    
    // Inject context into HTTP request header `sw8`
    span, err := tracer.CreateExitSpan(req.Context(), "/service/validate", "tomcat-service:8080", func(header string) error {
    		req.Header.Set(propagation.Header, header)
    		return nil
    })

    Tag

    We set tags into a span which is stored in the backend, but some tags have special purpose. OAP server may use them to aggregate metrics, generate topology map and etc.

    They are defined as constant in root package with prefix Tag.

    Plugins

    Go to go2sky-plugins repo to see all the plugins, click here.

    License

    Apache License 2.0. See LICENSE file for details.

    项目简介

    Distributed tracing and monitor SDK in Go for Apache SkyWalking APM

    发行版本

    当前项目没有发行版本

    贡献者 12

    全部贡献者

    开发语言

    • Go 94.7 %
    • Python 2.8 %
    • Makefile 2.6 %