Instrumente sua aplicação Go com um agente SkyWalking para enviar rastros distribuídos ao console do Managed Service for OpenTelemetry. Após o recebimento dos rastros, explore a topologia da aplicação, rastros, transações lentas, análise de erros e análises de SQL.
Dois agentes SkyWalking oferecem suporte ao Go:
|
Agente |
Estilo de instrumentação |
Status |
|
skywalking-go (recomendado) |
Não intrusivo — injeção em tempo de compilação via |
Mantido ativamente |
|
Go2Sky (legado) |
Intrusivo — requer hooks por plug-in no código-fonte |
Descontinuado, sem manutenção |
Use o skywalking-go, a menos que seu projeto já dependa do Go2Sky. O SkyWalking migra gradualmente os plug-ins do Go2Sky para o agente skywalking-go, que também adiciona suporte ao framework gRPC.
O ARMS também fornece um agente proprietário para Go, com suporte comercial. Ele permite instrumentação não intrusiva com mais recursos e maior estabilidade.
Enviar rastros com o agente skywalking-go
As etapas a seguir descrevem como compilar o agente skywalking-go, configurá-lo para o Managed Service for OpenTelemetry e recompilar seu projeto Go com instrumentação em tempo de compilação.
Etapa 1: Obter o endpoint do SkyWalking
Faça login no console do Managed Service for OpenTelemetry.
No painel de navegação à esquerda, clique em Cluster Configurations. Na página exibida, clique na aba Access point information.
Na barra de navegação superior, selecione uma região. Na seção Cluster Information, ative Show Token.
Defina o parâmetro Client como SkyWalking.
Copie o endpoint da coluna Related Information.

Se sua aplicação for executada em um ambiente de produção da Alibaba Cloud, use o endpoint de VPC. Caso contrário, use o endpoint público.
Etapa 2: Compilar o binário do agente
Clone e compile o agente skywalking-go:
git clone https://github.com/apache/skywalking-go.git
cd skywalking-go && make build
A compilação gera um executável no diretório skywalking-go/bin/. O nome do arquivo varia conforme o sistema operacional — por exemplo, skywalking-go-agent--darwin-amd64 no macOS.

Etapa 3: Adicionar o módulo SkyWalking ao projeto
Escolha um dos métodos abaixo:
Opção A — Importar no código
Adicione ao seu pacote principal:
package main
import (
_ "github.com/apache/skywalking-go"
)
Opção B — Injetar com o binário do agente
skywalking-go/bin/skywalking-go-agent--darwin-amd64 -inject path/to/your-project
Se o método de injeção falhar, use a Opção A.
Etapa 4: Configurar o agente
Crie um arquivo config.yaml com pelo menos os três parâmetros a seguir:
agent:
service_name: ${SW_AGENT_NAME:<your-service-name>}
reporter:
grpc:
backend_service: ${SW_AGENT_REPORTER_GRPC_BACKEND_SERVICE:<your-skywalking-endpoint>}
authentication: ${SW_AGENT_REPORTER_GRPC_AUTHENTICATION:<your-auth-token>}
Substitua os placeholders pelos seus valores:
|
Placeholder |
Descrição |
Exemplo |
|
|
Nome que identifica sua aplicação no console |
|
|
|
Endpoint obtido na Etapa 1 |
|
|
|
Token de autenticação exibido ao lado do endpoint |
|
Defina esses valores diretamente no arquivo config.yaml (recomendado) ou por variáveis de ambiente:
export SW_AGENT_NAME=my-go-service
export SW_AGENT_REPORTER_GRPC_BACKEND_SERVICE=xxx.api.aliyuncs.com:11800
export SW_AGENT_REPORTER_GRPC_AUTHENTICATION=abcdef123456
Desativar plug-ins específicos
Por padrão, o agente skywalking-go instrumenta todos os plug-ins suportados. Para excluir plug-ins específicos, adicione o parâmetro excluded:
plugin:
# Disable a single plug-in
excluded: ${SW_AGENT_PLUGIN_EXCLUDES:sql}
# Disable multiple plug-ins (comma-separated)
# excluded: ${SW_AGENT_PLUGIN_EXCLUDES:sql,gorm}
Etapa 5: Recompilar o projeto
Compile com a flag -toolexec apontando para o binário do agente e seu arquivo de configuração:
sudo go build -toolexec "path/to/skywalking-go-agent -config path/to/config.yaml" -a
Etapa 6: Iniciar a aplicação e verificar
Execute o binário compilado. O agente instrumenta automaticamente todos os plug-ins suportados e começa a relatar rastros via gRPC.
Após iniciar o projeto, o SkyWalking relata dados ao console do Managed Service for OpenTelemetry.
Referência de variáveis de ambiente
|
Variável de ambiente |
Descrição |
Padrão |
|
|
Nome da aplicação exibido no console |
Nenhum |
|
|
Nome da instância |
Gerado automaticamente |
|
|
Taxa de amostragem (0 a 1, onde 1 = 100%) |
|
|
|
Endpoint gRPC para relatório de rastros |
|
|
|
Token de autenticação |
Nenhum |
|
|
Lista separada por vírgulas de plug-ins a desativar |
Nenhum |
Plug-ins suportados
O agente skywalking-go instrumenta automaticamente as bibliotecas a seguir em tempo de compilação. Não é necessária instalação individual por biblioteca.
|
Biblioteca |
|
sql |
|
dubbo-go |
|
gear |
|
gin |
|
go-restful |
|
gorm |
|
http |
|
go-kratos v2 |
|
logrus |
|
go-micro v3.5.0 |
|
mongo |
|
go-resty v2.2.0 |
|
zap v1.16.0 |
Enviar rastros com o agente Go2Sky (legado)
O SkyWalking descontinuou o Go2Sky. Não aceita mais pull requests nem fornece atualizações. Use o agente skywalking-go para novos projetos.
Etapa 1: Configurar o reporter
Configure o reporter gRPC codificando os parâmetros diretamente ou definindo variáveis de ambiente.
Opção A — Codificar diretamente no projeto
report, err := reporter.NewGRPCReporter(
"<your-backend-server-address>",
reporter.WithAuthentication("<your-auth-token>"))
Opção B — Definir variáveis de ambiente
# Permanent -- add to your shell profile
export SW_AGENT_COLLECTOR_BACKEND_SERVICES=<your-collector-address>
export SW_AGENT_AUTHENTICATION=<your-auth-token>
# Then start your application (the agent reads these variables automatically)
Etapa 2: Criar um tracer
ServiceName := "<your-service-name>"
tracer, err := go2sky.NewTracer(ServiceName, go2sky.WithReporter(report))
Etapa 3: Adicionar hooks de plug-in
O Go2Sky exige um hook para cada biblioteca instrumentada. Consulte o repositório go2sky-plugins no GitHub — cada pasta de plug-in contém um README com instruções de integração.
Exemplo — framework gin:
package main
import (
"log"
"github.com/SkyAPM/go2sky"
v3 "github.com/SkyAPM/go2sky-plugins/gin/v3"
"github.com/SkyAPM/go2sky/reporter"
"github.com/gin-gonic/gin"
)
func main() {
// Use gRPC reporter for production
re, err := reporter.NewLogReporter()
if err != nil {
log.Fatalf("new reporter error %v \n", err)
}
defer re.Close()
tracer, err := go2sky.NewTracer("gin-server", go2sky.WithReporter(re))
if err != nil {
log.Fatalf("create tracer error %v \n", err)
}
gin.SetMode(gin.ReleaseMode)
r := gin.New()
// Use go2sky middleware with tracing
r.Use(v3.Middleware(r, tracer))
// Add your routes here
}
Etapa 4: Reiniciar a aplicação
Após adicionar os hooks, reinicie sua aplicação. Os rastros começarão a fluir para o console do Managed Service for OpenTelemetry.
Bibliotecas de plug-ins suportadas
Cada plug-in requer instalação separada via go get:
|
Biblioteca |
Comando de instalação |
|
sql |
|
|
dubbo-go |
|
|
gear |
|
|
gin |
|
|
go-restful |
|
|
gorm |
|
|
http |
|
|
go-kratos v2 |
|
|
logrus |
|
|
go-micro v3.5.0 |
|
|
mongo |
|
|
go-resty v2.2.0 |
|
|
zap v1.16.0 |
|
Referência de variáveis de ambiente
|
Variável de ambiente |
Descrição |
Padrão |
|
|
Nome da aplicação |
Nenhum |
|
|
Nome da camada da instância |
Nenhum |
|
|
Nome da instância |
Aleatório |
|
|
Taxa de amostragem (1 = amostragem completa) |
|
|
|
Endpoint do servidor para relatório de rastros |
Nenhum |
|
|
Token de autenticação |
Nenhum |
|
|
Intervalo de heartbeat em segundos |
|
|
|
Intervalo de busca de configuração dinâmica em segundos |
|
|
|
Tamanho do buffer da fila de spans |
|
|
|
Ativar hook de status do processo |
|
|
|
Rótulos de processo separados por vírgula |
Nenhum |
Perguntas frequentes
O que fazer se o comando inject do skywalking-go falhar?

Se o método -inject falhar, adicione a importação do SkyWalking diretamente no seu pacote principal:
import _ "github.com/apache/skywalking-go"
Em seguida, recompile com -toolexec conforme descrito na Etapa 5.
Por que o console mostra rastros quebrados em chamadas entre processos com Go2Sky?
O Managed Service for OpenTelemetry correlaciona spans por IDs de rastro transportados nos cabeçalhos HTTP. Se os rastros parecerem desconectados entre serviços, o contexto de rastro não está sendo propagado corretamente.
Para corrigir isso, crie spans de entrada e saída que propaguem o contexto de rastro pelas fronteiras HTTP:
// CreateEntrySpan -- extract trace context from an incoming HTTP request
span, ctx, err := tracer.CreateEntrySpan(r.Context(), "/api/login", func(key string) (string, error) {
return r.Header.Get(key), nil
})
// CreateExitSpan -- inject trace context into an outgoing HTTP request
span, err := tracer.CreateExitSpan(req.Context(), "/service/validate", "tomcat-service:8080", func(key, value string) error {
req.Header.Set(key, value)
return nil
})
Para spans dentro do mesmo processo (sem fronteira de rede), use CreateLocalSpan:
span, ctx, err := tracer.CreateLocalSpan(context.Background())
subSpan, newCtx, err := tracer.CreateLocalSpan(ctx)
Toda chamada HTTP que cruza uma fronteira de processo deve transportar o contexto de rastro. Sem CreateEntrySpan e CreateExitSpan em cada fronteira, o serviço downstream inicia um novo rastro desconectado.
Código de exemplo
Para um exemplo funcional completo, consulte o repositório skywalking-demo no GitHub.