Skip to content

Commit 3da6567

Browse files
sujitnewrelicsujitnewrelic
authored
Merge pull request #22613 from newrelic/daily-release/01-05-26-morning
Daily release/01 05 26 morning
2 parents 7d1f3bb + ef0fbca commit 3da6567

File tree

6 files changed

+416
-163
lines changed

6 files changed

+416
-163
lines changed

‎src/content/docs/apm/agents/go-agent/get-started/go-agent-compatibility-requirements.mdx‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -602,3 +602,16 @@ The Go agent integrates with other features to give you observability across you
602602
</tr>
603603
</tbody>
604604
</table>
605+
606+
## Next steps
607+
608+
Now that you've confirmed your system meets the requirements:
609+
610+
1. **[Install the Go agent](/docs/apm/agents/go-agent/installation/install-new-relic-go)** - Follow our step-by-step installation guide
611+
2. **[Configure the agent](/docs/apm/agents/go-agent/configuration)** - Customize agent behavior for your environment
612+
3. **[Add instrumentation](/docs/apm/agents/go-agent/instrumentation)** - Monitor specific operations in your application
613+
4. **[Explore features](/docs/apm/agents/go-agent/features)** - Discover advanced monitoring capabilities
614+
615+
<Callout variant="tip">
616+
**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.
617+
</Callout>

‎src/content/docs/apm/agents/go-agent/installation/install-new-relic-go.mdx‎

Lines changed: 292 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,72 +1,325 @@
11
---
2-
title: 'Install New Relic for Go '
2+
title: 'Install New Relic for Go'
33
tags:
44
- Agents
55
- Go agent
66
- Installation
77
translate:
88
- jp
9-
metaDescription: How to install New Relic's Go agent to monitor performance of your Go language applications and microservices.
9+
metaDescription: Step-by-step guide to install New Relic's Go agent and start monitoring your Go applications with detailed performance insights.
1010
redirects:
1111
- /docs/agents/go-agent/installation/install-new-relic-go
1212
- /docs/agents/go-agent/get-started/get-new-relic-go
1313
- /docs/agents/go-agent/get-started/install-new-relic-go
1414
freshnessValidatedDate: never
1515
---
1616

17-
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.
17+
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.
1818

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

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

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

31-
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).
28+
* **Get your license key** - You'll need your <InlinePopover type="licenseKey"/> during installation.
3229

33-
## Install the Go agent [#get-new-relic]
30+
## Installation steps
3431

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

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

36+
**Install the Go agent**
37+
38+
Add the New Relic Go agent to your project:
39+
40+
```bash
41+
go get github.com/newrelic/go-agent/v3/newrelic
42+
```
43+
44+
<Callout variant="tip">
45+
**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.
46+
</Callout>
47+
48+
</Step>
49+
50+
<Step>
51+
52+
**Import the agent**
53+
54+
Add the import to your Go application:
55+
56+
```go
57+
import "github.com/newrelic/go-agent/v3/newrelic"
58+
```
59+
60+
</Step>
61+
62+
<Step>
63+
64+
**Initialize the agent**
65+
66+
Create an application instance in your `main` function:
67+
68+
```go
69+
func main() {
70+
app, err := newrelic.NewApplication(
71+
newrelic.ConfigAppName("My Go Application"),
72+
newrelic.ConfigLicense(os.Getenv("NEW_RELIC_LICENSE_KEY")),
73+
)
74+
if err != nil {
75+
log.Fatal("Failed to create New Relic application:", err)
76+
}
77+
78+
// Wait for the application to connect
79+
if err := app.WaitForCompletion(5 * time.Second); err != nil {
80+
log.Println("Warning: New Relic application did not connect:", err)
81+
}
82+
83+
// Your application code here
84+
}
85+
```
86+
87+
<Callout variant="important">
88+
**Security best practice**: Always use environment variables for your license key instead of hardcoding it in your source code.
89+
</Callout>
90+
91+
</Step>
92+
93+
<Step>
94+
95+
**Instrument your web handlers**
96+
97+
For HTTP applications, wrap your handlers to monitor web transactions:
98+
99+
```go
100+
// Method 1: Wrap individual handlers
101+
http.HandleFunc(newrelic.WrapHandleFunc(app, "/", indexHandler))
102+
http.HandleFunc(newrelic.WrapHandleFunc(app, "/users", usersHandler))
103+
http.HandleFunc(newrelic.WrapHandleFunc(app, "/api/data", apiHandler))
104+
105+
// Method 2: Wrap your entire mux (recommended for many routes)
106+
mux := http.NewServeMux()
107+
mux.HandleFunc("/", indexHandler)
108+
mux.HandleFunc("/users", usersHandler)
109+
mux.HandleFunc("/api/data", apiHandler)
110+
111+
http.ListenAndServe(":8080", newrelic.WrapListen(app, mux))
112+
```
113+
114+
</Step>
115+
116+
<Step>
117+
118+
**Add basic error handling**
119+
120+
Capture errors in your handlers:
121+
122+
```go
123+
func usersHandler(w http.ResponseWriter, r *http.Request) {
124+
// Get transaction from request context
125+
txn := newrelic.FromContext(r.Context())
126+
127+
user, err := getUserFromDatabase(r.URL.Query().Get("id"))
128+
if err != nil {
129+
// Report error to New Relic
130+
txn.NoticeError(err)
131+
http.Error(w, "User not found", http.StatusNotFound)
132+
return
133+
}
134+
135+
// Add custom attributes
136+
txn.AddAttribute("user.id", user.ID)
137+
txn.AddAttribute("user.tier", user.Tier)
138+
139+
// Return user data
140+
json.NewEncoder(w).Encode(user)
141+
}
142+
```
143+
144+
</Step>
145+
146+
<Step>
147+
148+
**Deploy and verify**
149+
150+
1. **Set your environment variable**:
39151
```bash
40-
go get github.com/newrelic/go-agent/v3/newrelic
152+
export NEW_RELIC_LICENSE_KEY="your-license-key-here"
41153
```
42-
2. Import the `github.com/newrelic/go-agent/v3/newrelic` package in your application.
43154

44-
```go
45-
import "github.com/newrelic/go-agent/v3/newrelic"
155+
2. **Compile and run your application**:
156+
```bash
157+
go build -o myapp
158+
./myapp
46159
```
47-
3. Initialize the Go agent by adding the following in the `main` function or in an `init` block:
48160

49-
```go
50-
app, err := newrelic.NewApplication(
51-
newrelic.ConfigAppName("Your Application Name"),
52-
newrelic.ConfigLicense("YOUR_NEW_RELIC_LICENSE_KEY")
53-
)
54-
```
55-
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:
161+
3. **Generate some traffic** by visiting your application URLs
56162

57-
```go
58-
http.HandleFunc(newrelic.WrapHandleFunc(app, "/users", usersHandler))
59-
```
60-
5. [Instrument other transactions](/docs/agents/go-agent/get-started/instrument-go-transactions) you want to monitor.
61-
6. Optional: Instrument [segments](/docs/agents/go-agent/get-started/instrument-go-segments) for an extra level of timing detail.
62-
7. Compile and deploy your application.
163+
4. **Check New Relic** within 2-3 minutes at [one.newrelic.com](https://one.newrelic.com/apm)
164+
165+
</Step>
166+
167+
</Steps>
168+
169+
## Installation examples
170+
171+
### Simple HTTP server
172+
173+
```go
174+
package main
175+
176+
import (
177+
"fmt"
178+
"log"
179+
"net/http"
180+
"os"
181+
"time"
182+
183+
"github.com/newrelic/go-agent/v3/newrelic"
184+
)
185+
186+
func main() {
187+
// Initialize New Relic
188+
app, err := newrelic.NewApplication(
189+
newrelic.ConfigAppName("Simple Go Server"),
190+
newrelic.ConfigLicense(os.Getenv("NEW_RELIC_LICENSE_KEY")),
191+
)
192+
if err != nil {
193+
log.Fatal(err)
194+
}
195+
196+
// Simple handler
197+
http.HandleFunc(newrelic.WrapHandleFunc(app, "/", func(w http.ResponseWriter, r *http.Request) {
198+
fmt.Fprintf(w, "Hello, World!")
199+
}))
200+
201+
log.Println("Server starting on :8080")
202+
log.Fatal(http.ListenAndServe(":8080", nil))
203+
}
204+
```
205+
206+
### Gin framework integration
207+
208+
```go
209+
package main
210+
211+
import (
212+
"os"
213+
214+
"github.com/gin-gonic/gin"
215+
"github.com/newrelic/go-agent/v3/integrations/nrgin"
216+
"github.com/newrelic/go-agent/v3/newrelic"
217+
)
218+
219+
func main() {
220+
// Initialize New Relic
221+
app, _ := newrelic.NewApplication(
222+
newrelic.ConfigAppName("Gin Application"),
223+
newrelic.ConfigLicense(os.Getenv("NEW_RELIC_LICENSE_KEY")),
224+
)
225+
226+
// Set up Gin with New Relic middleware
227+
r := gin.Default()
228+
r.Use(nrgin.Middleware(app))
229+
230+
r.GET("/", func(c *gin.Context) {
231+
c.JSON(200, gin.H{"message": "Hello, World!"})
232+
})
233+
234+
r.Run(":8080")
235+
}
236+
```
237+
238+
### Background job monitoring
239+
240+
```go
241+
func processBackgroundJob(app *newrelic.Application, jobData JobData) {
242+
// Create a background transaction
243+
txn := app.StartTransaction("background-job")
244+
defer txn.End()
245+
246+
// Add job context
247+
txn.AddAttribute("job.id", jobData.ID)
248+
txn.AddAttribute("job.type", jobData.Type)
249+
250+
// Process job with error handling
251+
if err := processJob(jobData); err != nil {
252+
txn.NoticeError(err)
253+
log.Printf("Job %s failed: %v", jobData.ID, err)
254+
return
255+
}
256+
257+
log.Printf("Job %s completed successfully", jobData.ID)
258+
}
259+
```
260+
261+
## What happens next?
262+
263+
After completing the basic installation, you'll immediately see:
264+
265+
- **APM dashboard** with response times, throughput, and error rates for your HTTP endpoints
266+
- **Transaction traces** showing the slowest web requests
267+
- **Basic error tracking** for errors reported via `txn.NoticeError()`
268+
269+
To unlock additional monitoring capabilities, you'll need to add more instrumentation:
270+
271+
- **Database monitoring** - Requires [database segment instrumentation](/docs/apm/agents/go-agent/instrumentation/instrument-go-segments)
272+
- **External service tracking** - Requires [external segment instrumentation](/docs/apm/agents/go-agent/instrumentation/instrument-go-segments)
273+
- **Custom metrics and events** - Requires [custom instrumentation](/docs/apm/agents/go-agent/instrumentation/create-custom-metrics-go)
274+
275+
## Troubleshooting
276+
277+
If you don't see data after installation:
278+
279+
1. **Check your application logs** for New Relic connection messages
280+
2. **Verify your license key** is correct and not expired
281+
3. **Ensure network connectivity** to New Relic (ports 80/443)
282+
4. **Review the [troubleshooting guide](/docs/apm/agents/go-agent/troubleshooting/no-data-appears-go)** for detailed help
283+
284+
<Callout variant="tip">
285+
**Enable debug logging** to see what the agent is doing:
286+
```go
287+
config := newrelic.NewConfig("My App", os.Getenv("NEW_RELIC_LICENSE_KEY"))
288+
config.Logger = newrelic.NewDebugLogger(os.Stdout)
289+
app, _ := newrelic.NewApplication(config)
290+
```
291+
</Callout>
292+
293+
## Next steps
294+
295+
Now that you have basic monitoring set up, you can enhance your observability through **configuration** and **instrumentation**:
296+
297+
- **Configuration** controls how the agent behaves globally across your entire application
298+
- **Instrumentation** adds monitoring code to specific operations you want to track
299+
300+
### Configure the agent
301+
302+
Use [agent configuration](/docs/apm/agents/go-agent/configuration) to control global behavior and achieve:
303+
304+
- **[Enable distributed tracing](/docs/apm/agents/go-agent/configuration/distributed-tracing-go-agent)** - Trace requests across multiple services
305+
- **[Control logging](/docs/apm/agents/go-agent/configuration/go-agent-logging)** - Set debug levels and log destinations
306+
- **[Set performance thresholds](/docs/apm/agents/go-agent/configuration/go-agent-configuration)** - Configure when queries are considered "slow"
307+
- **[Enable security features](/docs/apm/agents/go-agent/configuration/go-agent-configuration)** - Turn on high-security mode
308+
309+
### Add instrumentation
63310

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

66-
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).
313+
- **[Monitor database queries](/docs/apm/agents/go-agent/instrumentation/instrument-go-segments)** - Track SQL performance and slow queries
314+
- **[Track external API calls](/docs/apm/agents/go-agent/instrumentation/instrument-go-segments)** - Monitor third-party service calls
315+
- **[Monitor background jobs](/docs/apm/agents/go-agent/instrumentation/instrument-go-transactions)** - Track non-web transactions
316+
- **[Create custom metrics](/docs/apm/agents/go-agent/instrumentation/create-custom-metrics-go)** - Monitor business-specific KPIs
67317

68-
<InstallFeedback/>
318+
### Advanced features and monitoring
69319

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

72-
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).
323+
<Callout variant="tip">
324+
**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.
325+
</Callout>

0 commit comments

Comments
 (0)