Skip to content

Apm restruring 1 #21911

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: develop
Choose a base branch
from
Open

Apm restruring 1 #21911

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
e1ff3d5
wip
cbehera-newrelic Sep 25, 2025
b9ae221
wip
cbehera-newrelic Oct 14, 2025
3ac90d0
wip
cbehera-newrelic Oct 29, 2025
5761683
fixed the mdx issue
cbehera-newrelic Nov 3, 2025
a1145a8
Merge branch 'develop' into APM-restruring-1
akashreddy-nr Nov 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions ...nt/docs/apm/agents/go-agent/get-started/go-agent-compatibility-requirements.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -602,3 +602,16 @@ The Go agent integrates with other features to give you observability across you
</tr>
</tbody>
</table>

## Next steps

Now that you've confirmed your system meets the requirements:

1. **[Install the Go agent](/docs/apm/agents/go-agent/installation/install-new-relic-go)** - Follow our step-by-step installation guide
2. **[Configure the agent](/docs/apm/agents/go-agent/configuration)** - Customize agent behavior for your environment
3. **[Add instrumentation](/docs/apm/agents/go-agent/instrumentation)** - Monitor specific operations in your application
4. **[Explore features](/docs/apm/agents/go-agent/features)** - Discover advanced monitoring capabilities

<Callout variant="tip">
**Using a specific framework?** Many of the integrations listed above have specific setup instructions. Check the [GitHub examples](https://github.com/newrelic/go-agent/tree/master/v3/integrations) for your framework to get started quickly.
</Callout>
331 changes: 292 additions & 39 deletions src/content/docs/apm/agents/go-agent/installation/install-new-relic-go.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,72 +1,325 @@
---
title: 'Install New Relic for Go '
title: 'Install New Relic for Go'
tags:
- Agents
- Go agent
- Installation
translate:
- jp
metaDescription: How to install New Relic's Go agent to monitor performance of your Go language applications and microservices.
metaDescription: Step-by-step guide to install New Relic's Go agent and start monitoring your Go applications with detailed performance insights.
redirects:
- /docs/agents/go-agent/installation/install-new-relic-go
- /docs/agents/go-agent/get-started/get-new-relic-go
- /docs/agents/go-agent/get-started/install-new-relic-go
freshnessValidatedDate: never
---

Our Go agent auto-instruments your code so you can start monitoring your Go language apps and microservices. You can use our launcher, or follow the instructions in this document to complete a basic Go agent installation.
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.

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

<ButtonLink
role="button"
to="https://one.newrelic.com/marketplace/install-data-source?state=697ccd5e-8b96-ff04-32c1-a3bc39a31255"
variant="primary"
>
Add Go data
</ButtonLink>
1. **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.

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

The Go agent requires Golang 1.17 or higher on Linux, macOS, or Windows. For more information, see [Go agent compatibility and requirements](/docs/agents/go-agent/get-started/go-agent-compatibility-requirements).
3. **Get your license key** - You'll need your <InlinePopover type="licenseKey"/> during installation.

## Install the Go agent [#get-new-relic]
## Installation steps

In order to install the Go agent, you need a <InlinePopover type="licenseKey"/>. Then, to install the agent:
<Steps>

1. From [github.com/newrelic/go-agent](https://github.com/newrelic/go-agent), use your preferred process; for example:
<Step>

**Install the Go agent**

Add the New Relic Go agent to your project:

```bash
go get github.com/newrelic/go-agent/v3/newrelic
```

<Callout variant="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.
</Callout>

</Step>

<Step>

**Import the agent**

Add the import to your Go application:

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

</Step>

<Step>

**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
}
```

<Callout variant="important">
**Security best practice**: Always use environment variables for your license key instead of hardcoding it in your source code.
</Callout>

</Step>

<Step>

**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))
```

</Step>

<Step>

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

</Step>

<Step>

**Deploy and verify**

1. **Set your environment variable**:
```bash
go get github.com/newrelic/go-agent/v3/newrelic
export NEW_RELIC_LICENSE_KEY="your-license-key-here"
```
2. Import the `github.com/newrelic/go-agent/v3/newrelic` package in your application.

```go
import "github.com/newrelic/go-agent/v3/newrelic"
2. **Compile and run your application**:
```bash
go build -o myapp
./myapp
```
3. Initialize the Go agent by adding the following in the `main` function or in an `init` block:

```go
app, err := newrelic.NewApplication(
newrelic.ConfigAppName("Your Application Name"),
newrelic.ConfigLicense("YOUR_NEW_RELIC_LICENSE_KEY")
)
```
4. [Instrument web transactions](/docs/agents/go-agent/get-started/instrument-go-transactions#http-handler-txns) by wrapping standard HTTP requests in your app code. For example:
3. **Generate some traffic** by visiting your application URLs

```go
http.HandleFunc(newrelic.WrapHandleFunc(app, "/users", usersHandler))
```
5. [Instrument other transactions](/docs/agents/go-agent/get-started/instrument-go-transactions) you want to monitor.
6. Optional: Instrument [segments](/docs/agents/go-agent/get-started/instrument-go-segments) for an extra level of timing detail.
7. Compile and deploy your application.
4. **Check New Relic** within 2-3 minutes at [one.newrelic.com](https://one.newrelic.com/apm)

</Step>

</Steps>

## 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](/docs/apm/agents/go-agent/instrumentation/instrument-go-segments)
- **External service tracking** - Requires [external segment instrumentation](/docs/apm/agents/go-agent/instrumentation/instrument-go-segments)
- **Custom metrics and events** - Requires [custom instrumentation](/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](/docs/apm/agents/go-agent/troubleshooting/no-data-appears-go)** for detailed help

<Callout variant="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)
```
</Callout>

## 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](/docs/apm/agents/go-agent/configuration) to control global behavior and achieve:

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

### Add instrumentation

## View your app's data in New Relic [#view-data]
Use [detailed instrumentation](/docs/apm/agents/go-agent/instrumentation) to monitor specific operations and achieve:

Wait a few minutes for your application to send data to New Relic. Then, check your app's performance in the [APM UI](/docs/apm/applications-menu/monitoring/apm-overview-page). If no data appears within a few minutes, follow the [troubleshooting tips](/docs/agents/go-agent/troubleshooting/no-data-appears-go).
- **[Monitor database queries](/docs/apm/agents/go-agent/instrumentation/instrument-go-segments)** - Track SQL performance and slow queries
- **[Track external API calls](/docs/apm/agents/go-agent/instrumentation/instrument-go-segments)** - Monitor third-party service calls
- **[Monitor background jobs](/docs/apm/agents/go-agent/instrumentation/instrument-go-transactions)** - Track non-web transactions
- **[Create custom metrics](/docs/apm/agents/go-agent/instrumentation/create-custom-metrics-go)** - Monitor business-specific KPIs

<InstallFeedback/>
### Advanced features and monitoring

## Keep your agent up to date [#update]
- **[Explore advanced features](/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

To take full advantage of New Relic's latest features, enhancements, and important security patches, keep your app's [Go agent up to date](/docs/agents/go-agent/installation/update-go-agent).
<Callout variant="tip">
**Keep your agent updated**: Regularly [update to the latest version](/docs/apm/agents/go-agent/installation/update-go-agent) to get new features, performance improvements, and security patches.
</Callout>
Loading
Loading