From d661f90c6973c66021ad0715657e627af9e9ccc2 Mon Sep 17 00:00:00 2001 From: jcountsNR <94138069+jcountsNR@users.noreply.github.com> Date: Mon, 7 Feb 2022 10:21:31 -0800 Subject: [PATCH] feat: updated text --- .../instrument-library/index.mdx | 16 ++- .../instrument-library/send-events.mdx | 131 +++++++++--------- 2 files changed, 79 insertions(+), 68 deletions(-) diff --git a/src/markdown-pages/contribute-to-quickstarts/instrument-library/index.mdx b/src/markdown-pages/contribute-to-quickstarts/instrument-library/index.mdx index faacbfb0f..db41b9dd2 100644 --- a/src/markdown-pages/contribute-to-quickstarts/instrument-library/index.mdx +++ b/src/markdown-pages/contribute-to-quickstarts/instrument-library/index.mdx @@ -4,17 +4,21 @@ template: 'OverviewTemplate' description: '' --- -If your looking to jump into building your own quickstart, the first step is instrumenting your own library to send data to New Relic. New Relic I/O gives end users the ability to slice and dice observability data around their application, server, etc. Setting up your library to get data into New Relic is critical to this process, so that the end users have a streamlined click-thorugh experience to see your data on our platform. You will need to instrument your library with at least one data type to be able to observe it via a dashboard or alert. +If you're looking to jump into building your own quickstart, the first step is instrumenting your own library to send data to New Relic. + +Instrumenting your library will provide you with all the data you need to build the rest of the quickstart, including unique dashboards and alerts which visualize your data and provide actionable information quickly. + +Instrumenting your library will also help your users in several ways, including quick and easy adoption from any user already using your library. Once your library is instrumented, users will be able to send their data from your library to New Relic with ease, and have quickly get into visualizing their data to get the most of what our platform and your platform has to offer. Alongside this, New Relic customers who are curious about your library will be able to see its events in their account just by installing your library and providing their New Relic license key. ## Observability Data Options - New Relic has [four types of observability data](https://docs.newrelic.com/docs/data-apis/understand-data/new-relic-data-types) which we call MELT data; *Metrics, Events, Logs, and Traces*. Each one handles a specific use case, so you'll have to decide which one fits your needs best. + You will need to instrument your library with at least one data type in order to observe it via a dashboard or alert. New Relic has [four API options](https://docs.newrelic.com/docs/data-apis/understand-data/new-relic-data-types) which we call MELT data; *Metrics, Events, Logs, and Traces*. Each one serves a different purpose in providing visibility into your library's behaviors and performance. Here is some context to help you decide: - - [Events](contribute-to-quickstarts/create-a-quickstart/instrument-library/send-events) **(Most Common)**: Events are used if you are capturing something occuring in your application, server, library, etc. For CI/CD applications this might be a capture of each time a job runs. For security applications this might be any time a threat is detected. - - [Logs](https://docs.newrelic.com/docs/logs/log-api/introduction-log-api/) **(Common)**: Logs should be used if your library uses multiple attributes (ie. nested key-value data), or if your library is set up already to use log drains. - - [Metrics](https://docs.newrelic.com/docs/data-apis/ingest-apis/metric-api/introduction-metric-api/) **(Uncommon)**: Metrics are generally collected as aggregated data or as a numeric status at a point in time. Most metrics can be sent or aggregated through events, which is why we recommend events instead. You might want to use metrics if you view the data at a very high level, and don't expect your users to need a more detailed analysis. - - [Traces](https://docs.newrelic.com/docs/distributed-tracing/trace-api/introduction-trace-api/) **(Uncommon)**: Traces should be used if you have your own tool that tracks tracing, and you want to instrument that into new relic. + - [Events](contribute-to-quickstarts/create-a-quickstart/instrument-library/send-events) : Events are used if you are capturing something occuring in your application, server, library, etc. For CI/CD applications this might be a capture of each time a job runs. For security applications, this might be any time a threat is detected. + - [Logs](https://docs.newrelic.com/docs/logs/log-api/introduction-log-api/) : Logs should be used if your library uses multiple attributes (ie. nested key-value data). an example of a log might be a a job which runs multiple sub-tasks in your system, all nested into one job record. Generally speaking, logs require more data to be sent to New Relic, but provide possibly the most information of the options listed. + - [Metrics](https://docs.newrelic.com/docs/data-apis/ingest-apis/metric-api/introduction-metric-api/) : Metrics are generally collected as aggregated data or as a numeric status at a point in time. Most metrics can be sent or aggregated through events, which is why we recommend events instead. You might want to use metrics if you view the data at a very high level, and don't expect your users to need a more detailed analysis. Note that metrics are generally only used if you want to limit the amount of Data sent to New Relic. + - [Traces](https://docs.newrelic.com/docs/distributed-tracing/trace-api/introduction-trace-api/) : Traces should be used if you have your own tool that tracks tracing, and you want to instrument that into new relic. diff --git a/src/markdown-pages/contribute-to-quickstarts/instrument-library/send-events.mdx b/src/markdown-pages/contribute-to-quickstarts/instrument-library/send-events.mdx index ca10928b6..274b2ba9e 100644 --- a/src/markdown-pages/contribute-to-quickstarts/instrument-library/send-events.mdx +++ b/src/markdown-pages/contribute-to-quickstarts/instrument-library/send-events.mdx @@ -8,17 +8,17 @@ tags: -This guide will walk you through how to instrument your application to send event data into the New Relic's [Event API](https://docs.newrelic.com/docs/data-apis/ingest-apis/introduction-event-api/). The Event API allow you to send events to New Relic without a need for an agent. First, let's cover what events are. An event is a record of something happening somewhere. What triggers the event and what data is captured is up to you to customize, which we'll discuss next. +This guide will walk you through how to instrument your application to send event data into the New Relic's [Event API](https://docs.newrelic.com/docs/data-apis/ingest-apis/introduction-event-api/). The Event API allow you to send events to New Relic without a need for an agent. First, let's cover what events are. An event is a record of something happening somewhere. Some examples might be a process start or stop, or a button click on an application, or a job running and completing. When the event is triggered, ## Capture Events in your Library -At New Relic, we report events to data objects also called events. These events have multiple attributes (key-value pairs). We name each event record in our system with the event-type key. +At New Relic, we report events to data objects also called events. These events have multiple attributes (key-value pairs). The event record is queryable on the New Relic platform by using the required attribute, `evnet-type`. ```json [{"event-type": "transaction"}] ``` -The event-type key is how you will query the event data from NRQL. using the above example, this is how we would query for the data in NRQL: +The event-type key is how you will query the event data from NRQL(New Relic's querying language). using the above example, this is how we would query for the data in NRQL: ```sql From transaction select * @@ -28,15 +28,18 @@ The rest in the event can be any custom key-value data, based on your library. W - [Formatting JSON](https://docs.newrelic.com/docs/data-apis/ingest-apis/introduction-event-api#instrument) ## Send your events to New Relic -There are a few ways we will discuss in order to send your event data into New Relic. We have our [telemetry SDK's](https://docs.newrelic.com/docs/data-apis/ingest-apis/telemetry-sdks-report-custom-telemetry-data), which are development kits instrumented to help you easily set up a POST request via several very common languages (C, Java, Python, .NET, etc.). We also have a basic curl command, which can be used on a windows or linux system to make a POST request to New Relic. We also have a prometheus option, if you use prometheus and have difficulty with the first two options. +Now we can get into the steps for getting your events into New Relic. +* As a prerequisite, you will need to give your users the ability to use your library (via webhook or other means) to set an environment variable with our New Relic License Key. Once that is done, you have several options for making the event request. +* First, we'll cover using a command *(curl/bash)*, which can be used in your application to make a POST request to our Event API. +* Next, We have our [Telemetry SDK's](https://docs.newrelic.com/docs/data-apis/ingest-apis/telemetry-sdks-report-custom-telemetry-data), or Software Development Kits, which are open source libraries written to make it easier to intrument your library to send Event data. ### New Relic License Key You will need to set up an environment variable for your users to input their [New Relic License key](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#ingest-license-key), or give an option for them to add it to the request header. The examples below will assume this variable is configured as `NEW_RELIC_INSERT_KEY`. -### Send events via a curl/PowerShell command +### Use a curl/PowerShell command -First, let's cover how you can send agentless data to New Relic, with just a simple command. These commands can be used in Linux or Windows environments. Here are some example requests for both +If your library is already instrumented to be able to add a command using a webhook or some other method, you can use this command to post events to our API. * Linux/Bash @@ -67,18 +70,39 @@ $gzipBody = $output.ToArray() Invoke-WebRequest -Headers $headers -Method Post -Body $gzipBody "https://insights-collector.newrelic.com/v1/accounts/events" ``` +### Use our SDK +New Relic has a set of open source API client libraries that send data to New Relic. These operate by using our API's for data ingest, and in this case our event API. We have two SDK's that work with events, and those are Python and Java. Here we will walk through how to install each, and give a code example using both SDK's. -### Using our SDK's +Once our SDK is installed and ready, you can use the library to easily set up the api call to New Relic. Again, both of these examples will assume that the NEW_RELIC_INSERT_KEY environment variable is configured, and remember that any end user will need to be able to reconfigure this variable to use this in your library. -New Relic has a set of open source API client libraries that send data to New Relic. These operate by using our API's for data ingest, and in this case our event API. We have two SDK's that work with events, and those are Python and Java. Here we will walk through how to install each, and give a code example using both SDK's. +### Python For Python, you'll need to install the `newrelic-telemetry-sdk` package. you can do this by using pip: ```bash -$ pip install newrelic-telemetry-sdk +pip install newrelic-telemetry-sdk +``` +Next you can use the event client to send your event data +```Python +import os +import time +from newrelic_telemetry_sdk import Event, EventClient + +#Replace with your event data +event = Event( + "RateLimit", {"path": "/v1/endpoint", "accountId": 1000, "rejectRatio": 0.1} +) + +event_client = EventClient(os.environ["NEW_RELIC_INSERT_KEY"]) +response = event_client.send(event) +response.raise_for_status() +print("Event sent successfully!") + ``` -For Java, you will need to set up several dependencies: +### Java + +Here is an example using Java. You can either download and use gradle or use the ./gradlew command. [Here](https://github.com/newrelic/newrelic-telemetry-sdk-java/tree/main/telemetry_examples#telemetry-examples) is our repo for a full list of examples and how to use them. ```java //Maven Dependencies @@ -95,76 +119,59 @@ For Java, you will need to set up several dependencies: //Gradle Dependencies implementation("com.newrelic.telemetry:telemetry-core:0.13.1") implementation("com.newrelic.telemetry:telemetry-http-okhttp:0.13.1") -``` - -Once our SDK is installed and ready, you can use the library to easily set up the api call to New Relic. -* **Python** -```Python -import os -import time -from newrelic_telemetry_sdk import Event, EventClient - -# Record that a rate limit has been applied to an endpoint for an account -event = Event( - "RateLimit", {"path": "/v1/endpoint", "accountId": 1000, "rejectRatio": 0.1} -) - -event_client = EventClient(os.environ["NEW_RELIC_INSERT_KEY"]) -response = event_client.send(event) -response.raise_for_status() -print("Event sent successfully!") - -``` -* **Java** -```java //Imports -import static java.util.Collections.singleton; +package com.newrelic.telemetry.examples; import com.newrelic.telemetry.Attributes; +import com.newrelic.telemetry.EventBatchSenderFactory; import com.newrelic.telemetry.OkHttpPoster; -import com.newrelic.telemetry.TelemetryClient; import com.newrelic.telemetry.events.Event; -import com.newrelic.telemetry.events.EventBatch; -import java.net.InetAddress; -import java.time.Duration; -import java.time.temporal.ChronoUnit; -import java.util.UUID; +import com.newrelic.telemetry.events.EventBatchSender; +import com.newrelic.telemetry.events.EventBuffer; + +/** + * This is an example of sending an Event to New Relic. + * + *

An EventBatchSender is created by configuring an EventBatchSenderFactory object with a License + * Key. Then, an event is created with an EventType, Attributes, and the current time in + * milliseconds (UTC time). The event is added to an EventBuffer and sent via sender.sendBatch(). + * + *

To run this example, provide a command line argument for your License Key. + */ +public class EventExample { + public static void main(String[] args) throws Exception { -public class TelemetryClientExample { + String licenseKey = args[0]; + EventBatchSenderFactory factory = + EventBatchSenderFactory.fromHttpImplementation(OkHttpPoster::new); - public static void main(String[] args) throws Exception { - String insightsInsertKey = args[0]; + EventBatchSender sender = + EventBatchSender.create(factory.configureWith(NEW_RELIC_INSERT_KEY).useLicenseKey(true).build()); - // create a TelemetryClient with an http connect timeout of 10 seconds. - TelemetryClient telemetryClient = - TelemetryClient.create( - () -> new OkHttpPoster(Duration.of(10, ChronoUnit.SECONDS)), insightsInsertKey); - Attributes commonAttributes = - new Attributes() - .put("exampleName", "TelemetryClientExample") - .put("service.name", "TelemetryClientExampleService") - .put("host.hostname", InetAddress.getLocalHost().getHostName()) - .put("environment", "staging"); + EventBuffer eventBuffer = new EventBuffer(getCommonAttributes()); + Attributes attr = new Attributes(); + attr.put("foo", 1234); + attr.put("bar", "baz"); + attr.put("quux", true); - Span span = sendSampleEvent(telemetryClient, commonAttributes); + long timestamp = System.currentTimeMillis(); + Event event = new Event("SampleEvent", attr, timestamp); + eventBuffer.addEvent(event); - // make sure to shutdown the client, else the background Executor will stop the program from - // exiting. - telemetryClient.shutdown(); + sender.sendBatch(eventBuffer.createBatch()); } - private static void sendSampleEvent( - TelemetryClient telemetryClient, Attributes commonAttributes) { - Event event = new Event("TestEvent", new Attributes().put("testKey", "testValue")); - telemetryClient.sendBatch(new EventBatch(singleton(event), commonAttributes)); + private static Attributes getCommonAttributes() { + return new Attributes().put("exampleName", "CountExample"); } - +} ``` ### Alternative Options Other options available include using prometheus data, and installing a flex agent. We won't cover those in this guide, but here are some links to review these options. * [Prometheus Data](https://docs.newrelic.com/docs/infrastructure/prometheus-integrations/get-started/send-prometheus-metric-data-new-relic) - Prometheus data can be used by New Relic in two ways, [remote write](https://docs.newrelic.com/docs/infrastructure/prometheus-integrations/install-configure-remote-write/set-your-prometheus-remote-write-integration) and [OpenMetrics](https://docs.newrelic.com/docs/infrastructure/prometheus-integrations/install-configure-openmetrics/install-update-or-uninstall-your-prometheus-openmetrics-integration). At a very high level, remote write should be used if you manage your own prometheus servers, and OpenMetrics should be used if you do not. -* [Flex Agent](https://github.com/newrelic/nri-flex/blob/master/docs/basic-tutorial.md#flex-step-by-step-tutorial) - Our serverless flex agent is a possibility if the other options do not work for you, but might be a more complex integration to get started. \ No newline at end of file +* **Manual Implementation** - If you are using a code library that we do not have instrumented with an SDK, you can always manually instrument your own library to make a POST request to the [New Relic Event API](https://docs.newrelic.com/docs/data-apis/ingest-apis/introduction-event-api/). +* [Flex Agent](https://github.com/newrelic/nri-flex/blob/master/docs/basic-tutorial.md#flex-step-by-step-tutorial) - Our serverless flex agent is a possibility, but might be a more complex integration to get started.