# Go SDK

Install the Go metrics SDK, authenticate with an M2M credential, and call the Metrics API with a context-aware client.

The official Go SDK provides typed operation requests and responses, local request validation, automatic M2M token exchange, and typed API errors.

Use the [API reference](/api-reference) when you need the parameters and response schema for a specific operation.

## Requirements

The SDK requires Go 1.24 or newer. Add the module to your project:

```bash
go get github.com/omascloud/sdks/go/metrics
```

Import `core` for the shared authentication runtime and `metrics` for the generated Metrics client and models.

## Configure authentication

Use an exchange-only M2M credential for a service, job, or other unattended workload. On the **API tokens** page, [create a token](/docs/tokens#create-a-token-in-the-ui) and select **Exchange only** as its access mode. Store the credential in your secret manager and expose it to the process as `OMAS_M2M_TOKEN`; never commit it to source control.

The authentication provider exchanges the credential for short-lived, metrics-scoped access tokens and refreshes them automatically. A token created in **Direct** mode is not the credential this provider expects.

## Create a client

Create the provider and client once, reuse them across requests, and close both when the application shuts down:

```go
package main

import (
    "context"
    "fmt"
    "os"

    "github.com/omascloud/sdks/go/core"
    "github.com/omascloud/sdks/go/metrics"
)

func main() {
    authProvider, err := core.NewM2MAuthProvider(os.Getenv("OMAS_M2M_TOKEN"))
    if err != nil {
        panic(err)
    }
    defer authProvider.Close()

    client, err := metrics.NewClient(authProvider)
    if err != nil {
        panic(err)
    }
    defer client.Close()

    maxResults := int32(25)
    response, err := client.ListMetrics(
        context.Background(),
        metrics.ListMetricsOperationRequest{MaxResults: &maxResults},
    )
    if err != nil {
        panic(err)
    }

    for _, metric := range response.Metrics {
        fmt.Println(metric.Name)
    }
}
```

Pass a request-scoped context so callers can propagate cancellation and deadlines.

## Handle errors

Every documented service error has a generated Go type that you can inspect with `errors.As`. Each typed error embeds `*core.APIError`, which retains the HTTP status, error code, message, response headers, request ID, retry delay, and raw response body:

```go
var notFound *metrics.ResourceNotFoundError
if errors.As(err, &notFound) {
    fmt.Printf(
        "request %s failed with status %d\n",
        notFound.RequestID,
        notFound.StatusCode,
    )
    if notFound.Details != nil && notFound.Details.Field != nil {
        fmt.Printf("missing field: %s\n", *notFound.Details.Field)
    }
}
```

Unknown server error codes remain available as `*core.APIError`, so the client remains forward-compatible. Log the request ID when it is available and retry only when the failure and operation make that safe.

## Next steps

- Browse the [API reference](/api-reference) for operation parameters, responses, and documented errors.
- Review the [public SDK repository](https://github.com/omascloud/sdks) for source code and release information.
- Read [Metric rollups and resolution](/docs/metric-rollups-resolution) before choosing production query settings.