---
title: Install New Relic for Go
source: https://docs.newrelic.com/docs/apm/agents/go-agent/installation/install-new-relic-go
---

Get detailed performance insights for your Go applications by installing the New Relic Go agent. This guide walks you through a complete installation with examples for common Go application patterns.

## Before you begin

-   **Create a New Relic account** - If you don't have one already, [create a New Relic account](https://newrelic.com/signup). It's free, forever.

-   **Check compatibility** - Ensure you have:
    -   Go 1.19 or higher
    -   Linux, macOS, or Windows
    -   A supported [web framework or library](https://docs.newrelic.com/docs/apm/agents/go-agent/get-started/go-agent-compatibility-requirements)

-   **Get your license key** - You'll need your license key during installation.

## Installation steps

1.  **Install the Go agent**
    Add the New Relic Go agent to your project:
    ```bash
    go get github.com/newrelic/go-agent/v3/newrelic
    ```
    > #### 💡 TIP
    >
    > **Using Go modules?** The agent works seamlessly with Go modules. If you're using an older Go version, you may need to add the agent to your `vendor` folder.
2.  **Import the agent**
    Add the import to your Go application:
    ```go
    import "github.com/newrelic/go-agent/v3/newrelic"
    ```
3.  **Initialize the agent**
    Create an application instance in your `main` function:
    ```go
    func main() {
        app, err := newrelic.NewApplication(
            newrelic.ConfigAppName("My Go Application"),
            newrelic.ConfigLicense(os.Getenv("NEW_RELIC_LICENSE_KEY")),
        )
        if err != nil {
            log.Fatal("Failed to create New Relic application:", err)
        }

        // Wait for the application to connect
        if err := app.WaitForCompletion(5 * time.Second); err != nil {
            log.Println("Warning: New Relic application did not connect:", err)
        }

        // Your application code here
    }
    ```
    > #### ⚠️ IMPORTANT
    >
    > **Security best practice**: Always use environment variables for your license key instead of hardcoding it in your source code.
4.  **Instrument your web handlers**
    For HTTP applications, wrap your handlers to monitor web transactions:
    ```go
    // Method 1: Wrap individual handlers
    http.HandleFunc(newrelic.WrapHandleFunc(app, "/", indexHandler))
    http.HandleFunc(newrelic.WrapHandleFunc(app, "/users", usersHandler))
    http.HandleFunc(newrelic.WrapHandleFunc(app, "/api/data", apiHandler))

    // Method 2: Wrap your entire mux (recommended for many routes)
    mux := http.NewServeMux()
    mux.HandleFunc("/", indexHandler)
    mux.HandleFunc("/users", usersHandler)
    mux.HandleFunc("/api/data", apiHandler)

    http.ListenAndServe(":8080", newrelic.WrapListen(app, mux))
    ```
5.  **Add basic error handling**
    Capture errors in your handlers:
    ```go
    func usersHandler(w http.ResponseWriter, r *http.Request) {
        // Get transaction from request context
        txn := newrelic.FromContext(r.Context())

        user, err := getUserFromDatabase(r.URL.Query().Get("id"))
        if err != nil {
            // Report error to New Relic
            txn.NoticeError(err)
            http.Error(w, "User not found", http.StatusNotFound)
            return
        }

        // Add custom attributes
        txn.AddAttribute("user.id", user.ID)
        txn.AddAttribute("user.tier", user.Tier)

        // Return user data
        json.NewEncoder(w).Encode(user)
    }
    ```
6.  **Deploy and verify**
    1.  **Set your environment variable**:
        ```bash
        export NEW_RELIC_LICENSE_KEY="your-license-key-here"
        ```

    2.  **Compile and run your application**:
        ```bash
        go build -o myapp
        ./myapp
        ```

    3.  **Generate some traffic** by visiting your application URLs

    4.  **Check New Relic** within 2-3 minutes at [one.newrelic.com](https://one.newrelic.com/apm)

## Installation examples

### Simple HTTP server

```go
package main

import (
    "fmt"
    "log"
    "net/http"
    "os"
    "time"

    "github.com/newrelic/go-agent/v3/newrelic"
)

func main() {
    // Initialize New Relic
    app, err := newrelic.NewApplication(
        newrelic.ConfigAppName("Simple Go Server"),
        newrelic.ConfigLicense(os.Getenv("NEW_RELIC_LICENSE_KEY")),
    )
    if err != nil {
        log.Fatal(err)
    }

    // Simple handler
    http.HandleFunc(newrelic.WrapHandleFunc(app, "/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintf(w, "Hello, World!")
    }))

    log.Println("Server starting on :8080")
    log.Fatal(http.ListenAndServe(":8080", nil))
}
```

### Gin framework integration

```go
package main

import (
    "os"

    "github.com/gin-gonic/gin"
    "github.com/newrelic/go-agent/v3/integrations/nrgin"
    "github.com/newrelic/go-agent/v3/newrelic"
)

func main() {
    // Initialize New Relic
    app, _ := newrelic.NewApplication(
        newrelic.ConfigAppName("Gin Application"),
        newrelic.ConfigLicense(os.Getenv("NEW_RELIC_LICENSE_KEY")),
    )

    // Set up Gin with New Relic middleware
    r := gin.Default()
    r.Use(nrgin.Middleware(app))

    r.GET("/", func(c *gin.Context) {
        c.JSON(200, gin.H{"message": "Hello, World!"})
    })

    r.Run(":8080")
}
```

### Background job monitoring

```go
func processBackgroundJob(app *newrelic.Application, jobData JobData) {
    // Create a background transaction
    txn := app.StartTransaction("background-job")
    defer txn.End()

    // Add job context
    txn.AddAttribute("job.id", jobData.ID)
    txn.AddAttribute("job.type", jobData.Type)

    // Process job with error handling
    if err := processJob(jobData); err != nil {
        txn.NoticeError(err)
        log.Printf("Job %s failed: %v", jobData.ID, err)
        return
    }

    log.Printf("Job %s completed successfully", jobData.ID)
}
```

## What happens next?

After completing the basic installation, you'll immediately see:

-   **APM dashboard** with response times, throughput, and error rates for your HTTP endpoints
-   **Transaction traces** showing the slowest web requests
-   **Basic error tracking** for errors reported via `txn.NoticeError()`

To unlock additional monitoring capabilities, you'll need to add more instrumentation:

-   **Database monitoring** - Requires [database segment instrumentation](https://docs.newrelic.com/docs/apm/agents/go-agent/instrumentation/instrument-go-segments)
-   **External service tracking** - Requires [external segment instrumentation](https://docs.newrelic.com/docs/apm/agents/go-agent/instrumentation/instrument-go-segments)
-   **Custom metrics and events** - Requires [custom instrumentation](https://docs.newrelic.com/docs/apm/agents/go-agent/instrumentation/create-custom-metrics-go)

## Troubleshooting

If you don't see data after installation:

1.  **Check your application logs** for New Relic connection messages
2.  **Verify your license key** is correct and not expired
3.  **Ensure network connectivity** to New Relic (ports 80/443)
4.  **Review the [troubleshooting guide](https://docs.newrelic.com/docs/apm/agents/go-agent/troubleshooting/no-data-appears-go)** for detailed help

> #### 💡 TIP
>
> **Enable debug logging** to see what the agent is doing:
>
> ```go
> config := newrelic.NewConfig("My App", os.Getenv("NEW_RELIC_LICENSE_KEY"))
> config.Logger = newrelic.NewDebugLogger(os.Stdout)
> app, _ := newrelic.NewApplication(config)
> ```

## Next steps

Now that you have basic monitoring set up, you can enhance your observability through **configuration** and **instrumentation**:

-   **Configuration** controls how the agent behaves globally across your entire application
-   **Instrumentation** adds monitoring code to specific operations you want to track

### Configure the agent

Use [agent configuration](https://docs.newrelic.com/docs/apm/agents/go-agent/configuration) to control global behavior and achieve:

-   **[Enable distributed tracing](https://docs.newrelic.com/docs/apm/agents/go-agent/configuration/distributed-tracing-go-agent)** - Trace requests across multiple services
-   **[Control logging](https://docs.newrelic.com/docs/apm/agents/go-agent/configuration/go-agent-logging)** - Set debug levels and log destinations
-   **[Set performance thresholds](https://docs.newrelic.com/docs/apm/agents/go-agent/configuration/go-agent-configuration)** - Configure when queries are considered "slow"
-   **[Enable security features](https://docs.newrelic.com/docs/apm/agents/go-agent/configuration/go-agent-configuration)** - Turn on high-security mode

### Add instrumentation

Use [detailed instrumentation](https://docs.newrelic.com/docs/apm/agents/go-agent/instrumentation) to monitor specific operations and achieve:

-   **[Monitor database queries](https://docs.newrelic.com/docs/apm/agents/go-agent/instrumentation/instrument-go-segments)** - Track SQL performance and slow queries
-   **[Track external API calls](https://docs.newrelic.com/docs/apm/agents/go-agent/instrumentation/instrument-go-segments)** - Monitor third-party service calls
-   **[Monitor background jobs](https://docs.newrelic.com/docs/apm/agents/go-agent/instrumentation/instrument-go-transactions)** - Track non-web transactions
-   **[Create custom metrics](https://docs.newrelic.com/docs/apm/agents/go-agent/instrumentation/create-custom-metrics-go)** - Monitor business-specific KPIs

### Advanced features and monitoring

-   **[Explore advanced features](https://docs.newrelic.com/docs/apm/agents/go-agent/features)** like browser monitoring and custom events
-   **[Set up alerts](https://docs.newrelic.com/docs/alerts-applied-intelligence/new-relic-alerts/get-started/your-first-nrql-condition/)** for key performance metrics

> #### 💡 TIP
>
> **Keep your agent updated**: Regularly [update to the latest version](https://docs.newrelic.com/docs/apm/agents/go-agent/installation/update-go-agent) to get new features, performance improvements, and security patches.