github.com/newrelic/newrelic-client-go@v1.1.0/README.md (about) 1 [](https://github.com/newrelic/open-source-office/blob/master/examples/categories/index.md#category-community-project) 2 3 # newrelic-client-go 4 5 [](https://github.com/newrelic/newrelic-client-go/actions) 6 [](https://github.com/newrelic/newrelic-client-go/actions) 7 [](https://goreportcard.com/report/github.com/newrelic/newrelic-client-go) 8 [](https://godoc.org/github.com/newrelic/newrelic-client-go) 9 [](https://github.com/newrelic/newrelic-client-go/blob/main/LICENSE) 10 [](https://cla-assistant.io/newrelic/newrelic-client-go) 11 [](https://github.com/newrelic/newrelic-client-go/releases/latest) 12 13 The New Relic Client provides the building blocks for tools in the [Developer Toolkit](https://newrelic.github.io/observability-as-code), enabling quick access to the suite of New Relic APIs. As a library, it can also be leveraged within your own custom applications. 14 15 - [Getting Started and Example Usage](#getting-started-and-example-usage) 16 - [Upgrade to the latest version](#upgrade-to-the-latest-version) 17 - [Community](#community) 18 - [Development](#development) 19 - [Requirements](#requirements) 20 - [Building](#building) 21 - [Testing](#testing) 22 - [Integration tests](#integration-tests) 23 - [Go Version Support](#go-version-support) 24 - [Commit Messages](#commit-messages) 25 - [Format](#format) 26 - [Scope](#scope) 27 - [Documentation](#documentation) 28 - [Community Support](#community-support) 29 - [Issues / Enhancement Requests](#issues--enhancement-requests) 30 - [Contributing](#contributing) 31 - [Open Source License](#open-source-license) 32 33 <br> 34 35 ## Getting Started and Example Usage 36 37 Follow the steps below to add `github.com/newrelic/newrelic-client-go` as a dependency in your Go project. 38 39 1. In the root directory of your project, run `go get github.com/newrelic/newrelic-client-go@latest`. This will update your `go.mod` file with the latest version `newrelic-client-go`. 40 41 42 2. Import `newrelic-client-go` in your project code. 43 ```go 44 package main 45 46 import "github.com/newrelic/newrelic-client-go/newrelic" 47 48 func main() { 49 // Initialize the client. 50 client, err := newrelic.New(newrelic.ConfigPersonalAPIKey(os.Getenv("NEW_RELIC_API_KEY"))) 51 if err != nil { 52 // ... 53 } 54 } 55 ``` 56 57 3. Run `go mod tidy`. This will ensure all your dependencies are in sync with your code. 58 4. Your module's `go.mod` file should now be updated with the latest version of the client and should look similar to the following example (version number is hypothetical in the example below). 59 ``` 60 module example.com/yourmodule 61 62 go 1.18 63 64 require ( 65 github.com/newrelic/newrelic-client-go v0.80.0 66 ) 67 ``` 68 5. The example below demonstrates fetching New Relic entities. 69 ```go 70 package main 71 72 import ( 73 "fmt" 74 "os" 75 76 log "github.com/sirupsen/logrus" 77 78 "github.com/newrelic/newrelic-client-go/newrelic" 79 "github.com/newrelic/newrelic-client-go/pkg/entities" 80 ) 81 82 func main() { 83 // Initialize the client. 84 client, err := newrelic.New(newrelic.ConfigPersonalAPIKey(os.Getenv("NEW_RELIC_API_KEY"))) 85 if err != nil { 86 log.Fatal("error initializing client:", err) 87 } 88 89 // Search the current account for entities by name and type. 90 queryBuilder := entities.EntitySearchQueryBuilder{ 91 Name: "Example entity", 92 Type: entities.EntitySearchQueryBuilderTypeTypes.APPLICATION, 93 } 94 95 entitySearch, err := client.Entities.GetEntitySearch( 96 entities.EntitySearchOptions{}, 97 "", 98 queryBuilder, 99 []entities.EntitySearchSortCriteria{}, 100 ) 101 if err != nil { 102 log.Fatal("error searching entities:", err) 103 } 104 105 fmt.Printf("%+v\n", entitySearch.Results.Entities) 106 } 107 ``` 108 109 110 ## Upgrade to the latest version 111 112 1. Run the following command to tell Go to download the latest version. 113 ``` 114 go get github.com/newrelic/newrelic-client-go@latest 115 ``` 116 2. Run `go mod tidy` to sync your dependencies with your code. 117 3. Confirm your `go.mod` file is referencing the [latest version](https://github.com/newrelic/newrelic-client-go/releases/latest). 118 119 120 ## Community 121 122 New Relic hosts and moderates an online forum where customers can interact with New Relic employees as well as other customers to get help and share best practices. 123 124 - [Issues or Enhancement Requests](https://github.com/newrelic/newrelic-client-go/issues/new/choose) - Issues and enhancement requests can be submitted in the Issues tab of this repository. Please search for and review the existing open issues before submitting a new issue. 125 - [Contributors Guide](CONTRIBUTING.md) - Contributions are welcome. 126 - [Community discussion board](https://discuss.newrelic.com/c/build-on-new-relic/developer-toolkit) - Like all official New Relic open source projects, there's a related Community topic in the New Relic Explorers Hub. 127 128 Keep in mind that when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. If you'd like to execute our corporate CLA, or if you have any questions, please drop us an email at opensource@newrelic.com. 129 130 ## Development 131 132 ### Requirements 133 134 - Go 1.18+ 135 - GNU Make 136 - git 137 138 ### Building 139 140 This package does not generate any direct usable assets (it's a library). You can still run the build scripts to validate your code, and generate coverage information. 141 142 ```bash 143 # Default target is 'build' 144 $ make 145 146 # Explicitly run build 147 $ make build 148 149 # Locally test the CI build scripts 150 $ make build-ci 151 ``` 152 153 ### Testing 154 155 Before contributing, all linting and tests must pass. 156 157 Tests can be run directly via: 158 159 ```bash 160 # Tests and Linting 161 $ make test 162 163 # Only unit tests 164 $ make test-unit 165 166 # Only integration tests 167 $ make test-integration 168 ``` 169 170 #### Integration tests 171 172 Integration tests communicate with the New Relic API, and therefore require proper 173 account credentials to run properly. The suite makes use of secrets, which will 174 need to be configured in the environment or else the integraiton tests will be skipped 175 during a test run. To run the integration test suite, the following secrets will 176 need to be configured: 177 178 ```bash 179 NEW_RELIC_ACCOUNT_ID 180 NEW_RELIC_API_KEY 181 NEW_RELIC_INSIGHTS_INSERT_KEY 182 NEW_RELIC_LICENSE_KEY 183 NEW_RELIC_REGION 184 NEW_RELIC_TEST_USER_ID 185 ``` 186 187 Optional for debugging (defaults to `debug`): 188 189 ```bash 190 NEW_RELIC_LOG_LEVEL=trace 191 ``` 192 193 #### Go Version Support 194 195 We'll aim to support the latest supported release of Go, along with the 196 previous release. This doesn't mean that building with an older version of Go 197 will not work, but we don't intend to support a Go version in this project that 198 is not supported by the larger Go community. Please see the [Go 199 releases][go_releases] page for more details. 200 201 ### Commit Messages 202 203 Using the following format for commit messages allows for auto-generation of 204 the [CHANGELOG](CHANGELOG.md): 205 206 #### Format 207 208 `<type>(<scope>): <subject>` 209 210 | Type | Description | Change log? | 211 | ---------- | --------------------- | :---------: | 212 | `chore` | Maintenance type work | No | 213 | `docs` | Documentation Updates | Yes | 214 | `feat` | New Features | Yes | 215 | `fix` | Bug Fixes | Yes | 216 | `refactor` | Code Refactoring | No | 217 218 #### Scope 219 220 This refers to what part of the code is the focus of the work. For example: 221 222 **General:** 223 224 - `build` - Work related to the build system (linting, makefiles, CI/CD, etc) 225 - `release` - Work related to cutting a new release 226 227 **Package Specific:** 228 229 - `newrelic` - Work related to the New Relic package 230 - `http` - Work related to the `internal/http` package 231 - `alerts` - Work related to the `pkg/alerts` package 232 233 ### Documentation 234 235 **Note:** This requires the repo to be in your GOPATH [(godoc issue)](https://github.com/golang/go/issues/26827) 236 237 ```bash 238 $ make docs 239 ``` 240 241 ### Releasing 242 243 Releases are automated via the Release Github Action on merges to the default branch. No user interaction is required. 244 245 Using [svu](https://github.com/caarlos0/svu), commit messages are parsed to identify if a new release is needed, and to what extent. Here's the breakdown: 246 247 | Commit message | Tag increase | 248 | -------------------------------------------------------------------------------------- | ------------ | 249 | `fix: fixed something` | Patch | 250 | `feat: added new button to do X` | Minor | 251 | `fix: fixed thing xyz`<br><br>`BREAKING CHANGE: this will break users because of blah` | Major | 252 | `fix!: fixed something` | Major | 253 | `feat!: added blah` | Major | 254 | `chore: foo` | Nothing | 255 | `refactor: updated bar` | Nothing | 256 257 258 ## Community Support 259 260 New Relic hosts and moderates an online forum where you can interact with New Relic employees as well as other customers to get help and share best practices. Like all New Relic open source community projects, there's a related topic in the New Relic Explorers Hub. You can find our team's project topic/threads here: 261 262 [Developer ToolKit](https://discuss.newrelic.com/t/about-the-developer-toolkit-category/90159) 263 264 Please do not report issues with Top to New Relic Global Technical Support. Instead, visit the [`Explorers Hub`](https://discuss.newrelic.com/c/build-on-new-relic) for troubleshooting and best-practices. 265 266 ## Issues / Enhancement Requests 267 268 Issues and enhancement requests can be submitted in te [Issues tab of this repository](../../issues). Please search for and review the existing open issues before submitting a new issue. 269 270 ## Contributing 271 272 Contributions are welcome (and if you submit a Enhancement Request, expect to be invited to contribute it yourself :grin:). Please review our [Contributors Guide](CONTRIBUTING.md). 273 274 Keep in mind that when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. If you'd like to execute our corporate CLA, or if you have any questions, please drop us an email at opensource@newrelic.com. 275 276 ## Open Source License 277 278 This project is distributed under the [Apache 2 license](LICENSE). 279 280 [go_releases]: https://github.com/golang/go/wiki/Go-Release-Cycle