diff --git a/README.md b/README.md index d127fdcd..0e9ab81c 100644 --- a/README.md +++ b/README.md @@ -2,76 +2,70 @@ # New Relic OpenTelemetry Examples -This project contains examples illustrating usage of OpenTelemetry with New Relic. The examples aim to demonstrate the most common configurations we expect users to encounter, but isn't an exhaustive set of the ways you can use OpenTelemetry with New Relic. The examples generally adhere to the following principles: +This project contains examples illustrating usage of OpenTelemetry with New Relic. The examples aim to demonstrate the most common configurations we expect users to encounter, but isn't an exhaustive set of the ways you can use OpenTelemetry with New Relic. See [getting started guides](#getting-started-guides) and [other examples](#other-examples) for an index of available examples. -* Use the latest version of each language's OpenTelemetry API / SDK. -* Demonstrate using simple web service applications using a popular library / framework for each language. -* Demonstrate manual configuration of OpenTelemetry SDK to send data to New Relic for traces, metrics, and logs. - * Export data to New Relic over OTLP using protocol most idiomatic for the language, and defaulting to `http/protobuf` when there is no clear preference. - * Configure metrics to export using [delta](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk_exporters/otlp.md) temporality preference. - * Configure attribute limits to adhere to New Relic's limits on attribute length and count. -* Demonstrate auto instrumentation / agent configuration if offered by a language. - * Use environment variables / system properties to configure OTLP export, delta metrics export, and attribute limits aligned with manual configuration of SDK. +## Getting Started Guides -The following table details features currently demonstrated by the example. +The [Getting Started Guides](./getting-started-guides/README.md) demonstrate how to get started with OpenTelemetry and New Relic. Each of the languages listed illustrates how to add OpenTelemetry instrumentation to a simple web application, and configure OpenTelemetry to export data to New Relic. -`+` means the feature is covered, `-` means it is not covered, and `N/A` means feature is not available yet. +* .NET ([uninstrumented](./getting-started-guides/dotnet/Uninstrumented) / [instrumented](./getting-started-guides/dotnet/Instrumented)) +* Go ([uninstrumented](./getting-started-guides/go/uninstrumented) / [instrumented](./getting-started-guides/go/instrumented)) +* Java ([uninstrumented](./getting-started-guides/java/uninstrumented) / [instrumented](./getting-started-guides/java/instrumented)) +* Javascript ([uninstrumented](./getting-started-guides/javascript/uninstrumented) / [instrumented](./getting-started-guides/javascript/instrumented)) +* Python ([uninstrumented](./getting-started-guides/python/Uninstrumented) / [instrumented](./getting-started-guides/python/Instrumented)) +* Ruby ([uninstrumented](./getting-started-guides/ruby/uninstrumented) / [instrumented](./getting-started-guides/ruby/instrumented)) -| | Java | .NET | JS | Go | Python | Ruby | Collector[1] | -|-------------------------------------------------------------|------|------|-----|-----|--------|------|--------------| -| Configure SDK for New Relic | | | | | | | | -|     Collect traces | + | + | + | + | + | + | + | -|     Collect metrics | + | + | + | + | + | N/A | + | -|     Collect logs | + | + | N/A | N/A | N/A | N/A | + | -|     Export over OTLP | + | + | + | + | + | + | + | -|     Export metrics w/ delta temporality | + | + | + | + | + | N/A | + | -|     Adhere to attribute limits | + | + | + | + | + | + | + | -| Configure auto instrumentation / agent for New Relic | + | + | + | N/A | N/A | N/A | N/A | +## Other Examples +OpenTelemetry is a big ecosystem and everything doesn't fit into the goals of the [getting started guides](#getting-started-guides). These "other examples" demonstrate how other areas of OpenTelemetry fit in with New Relic. -**[1]** The collector has a different architecture and serves a different purpose than the language SDKs. Therefore, an apples-to-apples comparison to SDKs doesn't make sense. The table roughly indicates whether the feature is illustrated in the example collector configuration, even though the feature may not mean exactly the same thing as it does in the context of an SDK. +* Collector + * [OpenTelemetry Collector with OTLP Export to New Relic](./other-examples/collector) +* Java + * [OpenTelemetry Agent New Relic Config](./other-examples/java/agent-nr-config) + * [Micrometer Shim with OTLP Export](./other-examples/java/micrometer-shim) + * [Logs In Context with Log4j2 and Log Forwarding](./other-examples/java/logs-in-context-log4j2) +* .NET + * [OpenTelemetry Agent With New Relic Config](./other-examples/dotnet/agent-nr-config) +* Serverless + * AWS Lambda + * [OpenTelemetry Lambda .NET New Relic Config](./other-examples/serverless/aws-lambda/dotnet) + * [OpenTelemetry Lambda Java New Relic Config](./other-examples/serverless/aws-lambda/java) + * Azure Functions + * [OpenTelemetry Azure Functions Node New Relic Config](./other-examples/serverless/azure-functions/node/http-trigger-app) -See [Contribute](#contribute) for how to request OpenTelemetry/New Relic interactions be covered across all supported languages, or how to request a new language be added. - -## Getting Started +## How To Use 1. Clone this repo. 2. Follow the directions in the README of the example that you are interested in. -## Examples Index - -- [Getting Started Guides](./getting-started-guides/README.md) - - .NET ([uninstrumented](./getting-started-guides/dotnet/Uninstrumented) / [instrumented](./getting-started-guides/dotnet/Instrumented)) - - Go ([uninstrumented](./getting-started-guides/go/uninstrumented) / [instrumented](./getting-started-guides/go/instrumented)) - - Java ([uninstrumented](./getting-started-guides/java/uninstrumented) / [instrumented](./getting-started-guides/java/instrumented)) - - Javascript ([uninstrumented](./getting-started-guides/javascript/uninstrumented) / [instrumented](./getting-started-guides/javascript/instrumented)) - - Python ([uninstrumented](./getting-started-guides/python/Uninstrumented) / [instrumented](./getting-started-guides/python/Instrumented)) - - Ruby ([uninstrumented](./getting-started-guides/ruby/uninstrumented) / [instrumented](./getting-started-guides/ruby/instrumented)) -- Other Examples - - Collector - - [OpenTelemetry Collector with OTLP Export to New Relic](./other-examples/collector): Run the OpenTelemetry Collector with OTLP gRPC export to New Relic. - - Java - - [OpenTelemetry Agent New Relic Config](./other-examples/java/agent-nr-config): A Java application with the OpenTelemetry Agent configured for New Relic. - - [Micrometer Shim with OTLP Export](./other-examples/java/micrometer-shim): A Spring Boot Java application with micrometer installed, configured to use the OpenTelemetry micrometer shim and export to New Relic using OTLP. - - [Logs In Context With Log4j2](./other-examples/java/logs-in-context-log4j2): A Java application configured to include OpenTelemetry trace context on Log4j2 structured logs. - - .NET - - [OpenTelemetry Agent With New Relic Config](./other-examples/dotnet/agent-nr-config) A simple .NET application running with the OpenTelemetry Automatic Instrumentation Agent. - - Serverless - - AWS Lambda - - [OpenTelemetry Lambda .NET New Relic Config](./other-examples/serverless/aws-lambda/dotnet): An example AWS .NET Lambda function instrumented with OpenTelemetry. - - [OpenTelemetry Lambda Java New Relic Config](./other-examples/serverless/aws-lambda/java): An example AWS Java Lambda function instrumented with OpenTelemetry. - - Azure Functions - - [OpenTelemetry Azure Functions Node New Relic Config](./other-examples/serverless/azure-functions/node/http-trigger-app): An example Azure Function App that includes an HTTP trigger Azure Function instrumented using Open Telemetry. - ## Contribute We encourage your contributions to improve `newrelic-opentelemetry-examples`! Keep in mind that when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. You only have to sign the CLA one time per project. -Any contributions made outside the scope of the example matrix will not be considered. If your contribution is not for an existing OpenTelemetry/New Relic interaction and language, please first open an issue so the additional scope can be discussed. Any new OpenTelemetry/New Relic interaction will need to be covered by all supported languages. Any new language will need to cover all OpenTelemetry/New Relic interactions. If the scope is accepted, then the example matrix can be updated, and the new contribution will be reviewed. +Generally, we want to focus on the [getting started guides](#getting-started-guides). We're open to additional examples being added which are aligned with the [demo app specification](./getting-started-guides/demo-app-specification.md) and which have a volunteer [codeowner](#codeowners). + +We're more selective about additions to [other examples](#other-examples). We use the following criteria to evaluate additions: + +* Does the example demonstrate a very popular use case or recurring pain point? +* Has someone has volunteered to be a [codeowner](#codeowners)? +* Is there documentation - either in the readme or [docs.newrelic.com](https://docs.newrelic.com/) - which describes how to use the data produced by the example in New Relic? +* Is there continuous integration (i.e. [github action](.github/workflows/pull_request.yml)) ensuring that the example code functions? + +If the answer is yes to all those questions, we'll likely accept the contribution. If you have any questions, or to execute our corporate CLA (which is required if your contribution is on behalf of a company), drop us an email at opensource@newrelic.com. -**A note about vulnerabilities** +### Codeowners + +Codeowners for each example are defined in [codeowner](.github/CODEOWNERS). Each codeowner is responsible for: + +* Keeping dependencies (relatively) up to date. +* Responding to issues related to the example. + +Examples without a codeowner may be deleted. + +## Vulnerabilities As noted in our [security policy](https://github.com/newrelic/newrelic-opentelemetry-examples/security/policy), New Relic is committed to the privacy and security of our customers and their data. We believe that providing coordinated disclosure by security researchers and engaging with the security community are important means to achieve our security goals. diff --git a/getting-started-guides/README.md b/getting-started-guides/README.md index 4b2c9b22..592fc5d9 100644 --- a/getting-started-guides/README.md +++ b/getting-started-guides/README.md @@ -1,20 +1,12 @@ # Getting Started Guides -This repo holds the source code for the demo applications used in the Getting Started Guides. The demo app, available in a variety of languages, is a simple fibonacci app that caluclates the nth number in the fibonacci sequence, but only accepts an n value between 1-90. Input outside of that range is considered invalid and an exception will be thrown. +This repo holds the source code for the demo applications used in the [Getting Started Guides](https://docs.newrelic.com/docs/more-integrations/open-source-telemetry-integrations/opentelemetry/get-started/opentelemetry-get-started-intro/). -In the Getting Started Guides, you will learn about the platform capabilities New Relic offers for OTLP data and how to configure the OpenTelemetry SDK to optimize your observability experience in New Relic. This guide is designed so that you can choose one of the following paths: +Each language directory illustrates how to add OpenTelemetry instrumentation to a simple web application, and configure OpenTelemetry for an optimal New Relic experience. This includes exporting over OTLP, limiting attributes according to New Relic ingest limits, and more. -* Learn how to add OpenTelemetry instrumentation by using the uninstrumented version of the demo app and following the tutorial -* Inspect the code and apply relevant sections to your own apps +In order to provide some degree of uniformity, each sample app is written to comply with the [demo app specification](./demo-app-specification.md). Each language contains the following sub-directories: -Each language directory contains the following sub-directories: +* **Uninstrumented:** Contains the uninstrumented version of the app. +* **Instrumented:** Contains the instrumented versions of the app. The uninstrumented app is enhanced with OpenTelemetry based instrumentation to generate metrics, logs, and traces, and SDK configuration aligned with New Relic [best practices](https://docs.newrelic.com/docs/more-integrations/open-source-telemetry-integrations/opentelemetry/best-practices/opentelemetry-best-practices-overview/) to export telemetry to New Relic. -* Instrumented - - The instrumented versions of the demo app are instrumented with OpenTelemetry and configured according to our [best practices](https://docs.newrelic.com/docs/more-integrations/open-source-telemetry-integrations/opentelemetry/best-practices/opentelemetry-best-practices-overview/) to generate and export metrics, logs, and traces. - - Run the app of your preferred language following the README steps to export data to your New Relic account, or view a screenshot tour of New Relic features for OpenTelemetry data [here](https://developer.newrelic.com/collect-data/opentelemetry-manual/view/). Then, check out the guide for the relevant language to learn about the custom instrumentation and SDK configuration in the demo app that lights up these features. - -* Uninstrumented - - Contains the uninstrumented versions of the apps. Use these to follow along with the guide and learn how to add OpenTelemetry instrumentation. Then, check out the guide for the relevant language to learn about the custom instrumentation and SDK configuration in the demo app that lights up these features in your New Relic account. \ No newline at end of file +To run, please see the [Getting Started Guides](https://docs.newrelic.com/docs/more-integrations/open-source-telemetry-integrations/opentelemetry/get-started/opentelemetry-get-started-intro/) documentation and follow the instructions in the README of the root of each respective sample app. diff --git a/getting-started-guides/demo-app-specification.md b/getting-started-guides/demo-app-specification.md index 75dc6a34..7b3ffe31 100644 --- a/getting-started-guides/demo-app-specification.md +++ b/getting-started-guides/demo-app-specification.md @@ -7,10 +7,20 @@ * For valid input, `{"n":5,"result":5}` * For invalid input, `{"message":"n must be 1 <= n <= 90."}` -3. Must configure the OTLP exporter to send data to NR. Should use the standard environment variables for configuration rather than programmatic or other means: - * `OTEL_EXPORTER_OTLP_HEADERS=api-key=` - * `OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.nr-data.net:4317` - * `OTEL_SERVICE_NAME=getting-started-java` +3. Must configure the OpenTelemetry SDK according to New Relic best practices. + * Should use be kept up to date with latest version of OpenTelemetry API / SDK for language. + * Should export data to New Relic using OTLP, preferring `http/protobuf` where there is no clear preference. + * Should enable gzip compression. + * Should configure metrics w/ delta temporality. + * Should configure attribute limits. + * Should use the standard environment variables for configuration rather than programmatic or other means: + * `OTEL_SERVICE_NAME=getting-started-java` + * `OTEL_EXPORTER_OTLP_HEADERS=api-key=` + * `OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.nr-data.net:4318` + * `OTEL_EXPORTER_OTLP_COMPRESSION=gzip` + * `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf` + * `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=DELTA` + * `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT=4095` 4. Must accept input as `n`, with the valid input range as 1 <= n <= 90 5. The application must emit the following telemetry: