> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apitally.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Setup guide for Gin
> Set up the Apitally SDK for your Gin application.
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](https://gin-gonic.com) application. If you don't have an Apitally account yet, [sign up](https://app.apitally.io/?signup) 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](https://app.apitally.io/apps) and select Gin as your framework.
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.
```shell theme={null}
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](/sdk-reference/go/v1/configuration) immediately after `gin.Default()`, before registering other middleware and routes.
```go {4,10-13} theme={null}
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.
```go Middleware {3-8} theme={null}
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()
})
```
```go Route handler {3-8} theme={null}
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.
```go {4-6} theme={null}
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`](https://pkg.go.dev/log/slog), wrap your log handler with `apitally.NewSlogHandler`. It passes every record on to your handler unchanged.
```go theme={null}
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.
```go {2} theme={null}
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](https://github.com/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.
```go {4} theme={null}
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.
```go {3-5} theme={null}
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](/sdk-reference/go/v1/masking).
## 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.
```go {3} theme={null}
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](/sdk-reference/go/v1/sampling).
## 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`:
```shell theme={null}
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:
```go {1,4} theme={null}
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](/sdk-reference/go/v1/tracing).
## 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.
```go {11} theme={null}
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)
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.