Install New Relic for 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. It's free, forever.

• Check compatibility - Ensure you have:

  • Go 1.19 or higher
  • Linux, macOS, or Windows
  • A supported web framework or library

• Get your license key - You'll need your clave de licencia during installation.

Installation steps

$
go get github.com/newrelic/go-agent/v3/newrelic

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

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
}

// 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))

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)
}

Installation examples

Simple HTTP server

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

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

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
• External service tracking - Requires external segment instrumentation
• Custom metrics and events - Requires custom instrumentation

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 for detailed help

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 to control global behavior and achieve:

• Enable distributed tracing - Trace requests across multiple services
• Control logging - Set debug levels and log destinations
• Set performance thresholds - Configure when queries are considered "slow"
• Enable security features - Turn on high-security mode

Add instrumentation

Use detailed instrumentation to monitor specific operations and achieve:

• Monitor database queries - Track SQL performance and slow queries
• Track external API calls - Monitor third-party service calls
• Monitor background jobs - Track non-web transactions
• Create custom metrics - Monitor business-specific KPIs

Advanced features and monitoring

• Explore advanced features like browser monitoring and custom events
• Set up alerts for key performance metrics