Setup guide for Gin

This setup guide is for v1 of the Go SDK (currently in beta).

This page guides you through the setup of the Apitally SDK for your Gin application. If you don’t have an Apitally account yet, sign up before getting started. Once you’re done with this guide, you will be able to:

Get detailed metrics on API usage, errors, and performance
Track API adoption and usage by individual consumers
Log individual API requests, responses, and correlated application logs
See what’s causing slow API requests with traces
Monitor uptime and set up custom alerts

Requirements

Requires Go 1.25+ and Gin 1.9.1+.

Create app

To get started, create a new app in the Apitally dashboard and select Gin as your framework. Create app

You can also configure the environments (e.g. prod and dev) for your app, or simply accept the defaults. After submitting, you will see tailored setup instructions for your app. These include your write token and code snippets you can copy and paste into your project.

The write token (apt_...) provided in the setup instructions uniquely identifies your app for the purpose of data ingestion only. It does not grant any kind of read access to your data.

Install the SDK

Install the Apitally SDK as a dependency in your project.

go get github.com/apitally/apitally-go/gin-v1@v1.0.0-beta.2

Initialize Apitally

Call apitally.Init with your Gin engine and a configuration containing the write token and other configuration options immediately after gin.Default(), before registering other middleware and routes.

import (
    "github.com/gin-gonic/gin"

    apitally "github.com/apitally/apitally-go/gin-v1"
)

func main() {
    r := gin.Default()

    cfg := apitally.NewConfig()
    cfg.WriteToken = "your-write-token"
    cfg.Env = "dev" // or "prod" etc.
    apitally.Init(r, cfg)

    // ... register your middleware and routes ...
}

You can also set the APITALLY_WRITE_TOKEN and APITALLY_ENV environment variables instead of setting WriteToken and Env in code. Deploy your application with these changes, or restart it if you’re testing locally.

The basic setup is now complete. Metrics and logs will start appearing in the Apitally dashboard.

Identify consumers

Consumers are the users or applications calling your API. Identifying them lets you analyze and filter API traffic by consumer in Apitally. Call apitally.SetConsumer with the request context during request handling to associate the current request with a consumer identifier. You can call it wherever the consumer is known, such as in a route handler, existing middleware, or authentication code. You can also provide a display name, group, and custom attributes for each consumer.

r.Use(func(c *gin.Context) {
    if user := getCurrentUser(c); user != nil {
        apitally.SetConsumer(c.Request.Context(), apitally.Consumer{
            Identifier: user.ID,
            Name:       user.Name,                            // optional
            Group:      user.Group,                           // optional
            Attributes: map[string]string{"plan": user.Plan}, // optional
        })
    }
    c.Next()
})

r.GET("/items", func(c *gin.Context) {
    if user := getCurrentUser(c); user != nil {
        apitally.SetConsumer(c.Request.Context(), apitally.Consumer{
            Identifier: user.ID,
            Name:       user.Name,                            // optional
            Group:      user.Group,                           // optional
            Attributes: map[string]string{"plan": user.Plan}, // optional
        })
    }
    c.JSON(http.StatusOK, []string{"item1"})
})

Capture headers and bodies

Only response headers are captured by default. You can opt in to capture request headers as well as request and response bodies when initializing Apitally.

cfg := apitally.NewConfig()
cfg.WriteToken = "your-write-token"
cfg.Env = "dev" // or "prod" etc.
cfg.CaptureRequestHeaders = true
cfg.CaptureRequestBody = true
cfg.CaptureResponseBody = true
apitally.Init(r, cfg)

Capture application logs

To capture application logs written with log/slog, wrap your log handler with apitally.NewSlogHandler. It passes every record on to your handler unchanged.

handler := slog.NewJSONHandler(os.Stdout, nil)
slog.SetDefault(slog.New(apitally.NewSlogHandler(handler)))

Log with the request context, so Apitally can link the record to its request. Logs without a request context are not captured.

r.GET("/items", func(c *gin.Context) {
    slog.InfoContext(c.Request.Context(), "Listing items")
    c.JSON(http.StatusOK, []string{"item1"})
})

Do not wrap slog.Default().Handler() if you pass the result to slog.SetDefault, as this causes a deadlock on the first log call.

Capture validation errors

If you validate request data with go-playground/validator, pass the error to apitally.CaptureError with the request context. Apitally then counts validation errors by endpoint and field, so you can see which fields clients most often get wrong.

r.POST("/items", func(c *gin.Context) {
    var item Item
    if err := c.ShouldBindJSON(&item); err != nil {
        apitally.CaptureError(c.Request.Context(), err)
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }
    // ...
})

If you use c.Bind or c.BindJSON, or pass validation errors to c.Error(), Apitally captures them automatically for 400 or 422 responses. You don’t need to call apitally.CaptureError in those cases.

Mask sensitive information

The SDK automatically masks common sensitive query parameters, headers, and body fields. To mask additional data, pass regular expressions matching query parameter names, header names, or body field names to MaskQueryParams, MaskHeaders, or MaskBodyFields, respectively. Matching is case-insensitive.

cfg := apitally.NewConfig()
cfg.WriteToken = "your-write-token"
cfg.MaskQueryParams = []string{`^account_id$`}
cfg.MaskHeaders = []string{`^X-Custom-Key$`}
cfg.MaskBodyFields = []string{`^credit_card$`}
apitally.Init(r, cfg)

You can use the MaskRequestBody and MaskResponseBody callbacks to mask individual fields or entire bodies using custom logic. Use MaskLogRecord to mask or drop application log records. More information about masking is available here.

Sample requests

If your application receives a lot of traffic, you may want to sample requests to stay within your request logs quota. Metrics will continue to count every request regardless of sampling. Use SampleRate to capture logs and traces for a fraction of requests.

cfg := apitally.NewConfig()
cfg.WriteToken = "your-write-token"
cfg.SampleRate = 0.1 // capture logs and traces for 10% of requests
apitally.Init(r, cfg)

You can also use the SampleOnRequest and SampleOnResponse callbacks to make sampling decisions using custom logic. More information about sampling is available here.

Instrument third-party libraries

Instrumenting third-party libraries adds details about database queries, HTTP calls to external services, and other operations to your request traces. This lets you see how these operations contribute to API response times. Use OpenTelemetry instrumentation libraries to instrument the libraries you want to trace. For example, to trace database queries made with database/sql, install otelsql:

go get github.com/XSAM/otelsql

Then open your database with otelsql.Open instead of sql.Open, and pass the request context to your queries:

db, err := otelsql.Open("postgres", dsn)

r.GET("/items", func(c *gin.Context) {
    rows, err := db.QueryContext(c.Request.Context(), "SELECT name FROM items")
    // ...
})

Apitally sets up OpenTelemetry automatically, so you don’t need to create a tracer provider or configure an exporter. More information about tracing and instrumenting third-party libraries is available here.

Graceful shutdown

Apitally sends data in the background at regular intervals. To deliver the remaining data when your application exits, call apitally.Shutdown after your HTTP server has stopped.

srv := &http.Server{Addr: ":8080", Handler: r}
go srv.ListenAndServe()

ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
<-ctx.Done()

shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
srv.Shutdown(shutdownCtx)
apitally.Shutdown(shutdownCtx)

SDK reference

Setup guides

Requirements

Create app

Install the SDK

Initialize Apitally

Identify consumers

Capture headers and bodies

Capture application logs

Capture validation errors

Mask sensitive information

Sample requests

Instrument third-party libraries

Graceful shutdown

​Requirements

​Create app

​Install the SDK

​Initialize Apitally

​Identify consumers

​Capture headers and bodies

​Capture application logs

​Capture validation errors

​Mask sensitive information

​Sample requests

​Instrument third-party libraries

​Graceful shutdown

Requirements

Create app

Install the SDK

Initialize Apitally

Identify consumers

Capture headers and bodies

Capture application logs

Capture validation errors

Mask sensitive information

Sample requests

Instrument third-party libraries

Graceful shutdown