diff --git a/other-examples/collector/hcp-consul/.env b/other-examples/collector/hcp-consul/.env deleted file mode 100644 index 0a4a08a0..00000000 --- a/other-examples/collector/hcp-consul/.env +++ /dev/null @@ -1,14 +0,0 @@ -# New Relic API key to authenticate the call. -# docs: https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#license-key -NEW_RELIC_API_KEY= - -# The default US endpoint is set here. You can change the endpoint and port based on your requirements if needed. -# docs: https://docs.newrelic.com/docs/more-integrations/open-source-telemetry-integrations/opentelemetry/get-started/opentelemetry-set-up-your-app/#review-settings -NEW_RELIC_OTLP_ENDPOINT=https://otlp.nr-data.net/ - -# Set your authentication token for your HCP managed Consul enviroment. -# docs: https://developer.hashicorp.com/hcp/docs/consul/hcp-managed/access#generate-admin-token -HCP_ACCESS_TOKEN= -# Set your access URL to your HCP managed Consul environment. -# docs: https://developer.hashicorp.com/hcp/docs/consul/hcp-managed/access#get-access-url -HCP_ACCESS_URL= \ No newline at end of file diff --git a/other-examples/collector/hcp-consul/README.md b/other-examples/collector/hcp-consul/README.md index b6dbbe4c..07f98cea 100644 --- a/other-examples/collector/hcp-consul/README.md +++ b/other-examples/collector/hcp-consul/README.md @@ -1,36 +1,75 @@ -# HCP Consul OpenTelemetry metrics example setup +# Monitoring HCP Consul with OpenTelemetry Collector -This example shows a setup for running a prometheus OpenTelemetry Collector in a docker container to scrape metrics from [HCP Consul](https://developer.hashicorp.com/hcp/docs/consul) and post them the New Relic OTLP Collector Endpoint. +This simple example demonstrates monitoring [HCP Consul](https://developer.hashicorp.com/hcp/docs/consul) prometheus metrics with the [OpenTelemetry collector](https://opentelemetry.io/docs/collector/), using the [prometheus receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/prometheusreceiver) and sending the data to New Relic via OTLP. -**NOTE**: This is *not* for self-managed Consul, and will only work with HCP managed Consul. For self-managed Consul you will have to communicate with the [agent API](https://developer.hashicorp.com/consul/api-docs/agent). +## Requirements -## Prerequisites - -1. You must have a Docker daemon running. -2. You must have [Docker compose](https://docs.docker.com/compose/) installed . -3. You must have a [Consul cluster](https://developer.hashicorp.com/hcp/docs/consul) running in Consul Cloud. +* You need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. Docker desktop [includes a standalone Kubernetes server and client](https://docs.docker.com/desktop/kubernetes/) which is useful for local testing. +* [A New Relic account](https://one.newrelic.com/) +* [A New Relic license key](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#license-key) +* [An HCP Consul Account](https://developer.hashicorp.com/sign-up) with a running [cluster](https://developer.hashicorp.com/hcp/docs/consul) +* [A HCP Consul admin access token](https://developer.hashicorp.com/hcp/docs/consul/dedicated/access#generate-admin-token) ## Running the example -First, set your environment variables in the `.env` file in this directory. For more information on the individual variables, reference the docs available below. +1. Update the `NEW_RELIC_API_KEY` values `HCP_ACCESS_TOKEN` values in [secrets.yaml](./k8s/secrets.yaml) to your New Relic license key, and HCP Consule admin access token respectively. See [HCP Consule docs](https://developer.hashicorp.com/hcp/docs/consul/hcp-managed/access#generate-admin-token) for obtaining an access token. -Once the variables are set, run the following command from the root directory to start the collector. + ```yaml + # ...omitted for brevity + stringData: + # New Relic API key to authenticate the export requests. + # docs: https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#license-key + NEW_RELIC_API_KEY: + # Set your HCP Access Token API Key. + # docs: https://developer.hashicorp.com/hcp/docs/consul/hcp-managed/access#generate-admin-token + HCP_ACCESS_TOKEN: > + ``` + + * Note, be careful to avoid inadvertent secret sharing when modifying `secrets.yaml`. To ignore changes to this file from git, run `git update-index --skip-worktree k8s/secrets.yaml`. -```shell -cd ./other-examples/collector/hcp-consul + * If your account is based in the EU, update the `NEW_RELIC_OTLP_ENDPOINT` value in [collector.yaml](./k8s/collector.yaml) the endpoint to: [https://otlp.eu01.nr-data.net](https://otlp.eu01.nr-data.net) -docker compose up -``` + ```yaml + # ...omitted for brevity + env: + # The default US endpoint is set here. You can change the endpoint and port based on your requirements if needed. + # docs: https://docs.newrelic.com/docs/more-integrations/open-source-telemetry-integrations/opentelemetry/best-practices/opentelemetry-otlp/#configure-endpoint-port-protocol + - name: NEW_RELIC_OTLP_ENDPOINT + value: https://otlp.eu01.nr-data.net + ``` + +2. Set the `HCP_ACCESS_URL` env var value in [collector.yaml](./k8s/collector.yaml). See [HCP Consul docs](https://developer.hashicorp.com/hcp/docs/consul/hcp-managed/access#get-access-url) for details on obtaining org and workspace group ids. + + ```yaml + # ...omitted for brevity + # The HCP Consul access url. + # docs: https://developer.hashicorp.com/hcp/docs/consul/hcp-managed/access#get-access-url + - name: HCP_ACCESS_URL + value: + ``` + +3. Run the application with the following command. + + ```shell + kubectl apply -f k8s/ + ``` + + * When finished, cleanup resources with the following command. This is also useful to reset if modifying configuration. + + ```shell + kubectl delete -f k8s/ + ``` ## Viewing your data -To review your HCP Consul data in New Relic, navigate to your [metrics explorer](https://docs.newrelic.com/docs/query-your-data/explore-query-data/browse-data/introduction-data-explorer/) and filter for `consul`. +To review your HCP Consul data in New Relic, navigate to "New Relic -> Query Your Data". To list the metrics reported, query for: + +``` +FROM Metric SELECT uniques(metricName) WHERE otel.library.name = 'otelcol/prometheusreceiver' AND metricName LIKE 'consul%' +``` + +See [get started with querying](https://docs.newrelic.com/docs/query-your-data/explore-query-data/get-started/introduction-querying-new-relic-data/) for additional details on querying data in New Relic. -## Local Variable information +## Additional notes -| Variable | Description | Docs | -| -------- | ----------- | ---- | -| **NEW_RELIC_API_KEY** |New Relic Ingest API Key |[API Key docs](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/) | -| **NEW_RELIC_OTLP_ENDPOINT** |Default US OTLP endpoint is `https://otlp.nr-data.net` | [OTLP endpoint config docs](https://docs.newrelic.com/docs/more-integrations/open-source-telemetry-integrations/opentelemetry/get-started/opentelemetry-set-up-your-app/#review-settings) | -| **HCP_ACCESS_URL** | URL for communicating with your HCP managed Consul cluster |[Consul URL docs](https://developer.hashicorp.com/hcp/docs/consul/hcp-managed/access#get-access-url)| -| **HCP_ACCESS_TOKEN** | Consul admin token to authenticate with your HCP managed Consul Cluster| [Consul token docs](https://developer.hashicorp.com/hcp/docs/consul/hcp-managed/access#generate-admin-token) | +The prometheus receiver includes `service.name` and `service.instance.id` resource attributes derived from job name and target configured in `.receivers.prometheus.config.scrape_configs`. As documented [here](https://docs.newrelic.com/docs/more-integrations/open-source-telemetry-integrations/opentelemetry/best-practices/opentelemetry-best-practices-resources/#services), New Relic considers any data with `service.name` as a service despite the fact that not all prometheus data sources are services. As a result, you can find a `hcp-consul` entity under "New Relic -> All Entities -> Services - OpenTelemetry", although the panels will not contain data because the scraped metrics do not represent APM data. diff --git a/other-examples/collector/hcp-consul/collector.yaml b/other-examples/collector/hcp-consul/collector.yaml deleted file mode 100644 index 74968603..00000000 --- a/other-examples/collector/hcp-consul/collector.yaml +++ /dev/null @@ -1,36 +0,0 @@ -receivers: - prometheus: - config: - global: - scrape_interval: "60s" - scrape_configs: - - job_name: "hcp-consul-cluster" - scheme: "https" - dns_sd_configs: - - names: - - "$HCP_ACCESS_URL" - type: "A" - port: 443 - authorization: - credentials: "$HCP_ACCESS_TOKEN" - metrics_path: "/v1/agent/metrics" - - # Skipping TLS verification based on Consul docs(https://developer.hashicorp.com/hcp/docs/consul/monitor/metrics#prometheus). - tls_config: - insecure_skip_verify: true - -processors: - batch: - -exporters: - otlphttp: - endpoint: $NEW_RELIC_OTLP_ENDPOINT - headers: - api-key: $NEW_RELIC_API_KEY - -service: - pipelines: - metrics: - receivers: [prometheus] - processors: [batch] - exporters: [otlphttp] \ No newline at end of file diff --git a/other-examples/collector/hcp-consul/docker-compose.yaml b/other-examples/collector/hcp-consul/docker-compose.yaml deleted file mode 100644 index bc456615..00000000 --- a/other-examples/collector/hcp-consul/docker-compose.yaml +++ /dev/null @@ -1,14 +0,0 @@ -version: "3" - -services: - - otel-collector: - image: otel/opentelemetry-collector-contrib:0.92.0 - command: --config=/etc/otelcol/config.yaml - volumes: - - ./collector.yaml:/etc/otelcol/config.yaml - environment: - - NEW_RELIC_OTLP_ENDPOINT - - NEW_RELIC_API_KEY - - HCP_ACCESS_TOKEN - - HCP_ACCESS_URL diff --git a/other-examples/collector/hcp-consul/k8s/collector.yaml b/other-examples/collector/hcp-consul/k8s/collector.yaml new file mode 100644 index 00000000..b0ba1d37 --- /dev/null +++ b/other-examples/collector/hcp-consul/k8s/collector.yaml @@ -0,0 +1,94 @@ +--- +apiVersion: v1 +kind: Namespace +metadata: + name: nr-hcp-consul +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: collector-config + namespace: nr-hcp-consul + labels: + app.kubernetes.io/name: collector-config +data: + collector-config: | + receivers: + prometheus: + config: + scrape_configs: + - job_name: "hcp-consul" + scrape_interval: 60s # Do not go any lower than this or you'll hit rate limits + scheme: https + dns_sd_configs: + - names: + - "${HCP_ACCESS_URL}" + type: "A" + port: 443 + authorization: + credentials: "${HCP_ACCESS_TOKEN}" + metrics_path: "/v1/agent/metrics" + # Skipping TLS verification based on Consul docs(https://developer.hashicorp.com/hcp/docs/consul/monitor/metrics#prometheus). + tls_config: + insecure_skip_verify: true + + processors: + batch: + + exporters: + otlphttp: + endpoint: ${NEW_RELIC_OTLP_ENDPOINT} + headers: + api-key: ${NEW_RELIC_API_KEY} + + service: + pipelines: + metrics: + receivers: [prometheus] + processors: [batch] + exporters: [otlphttp] +--- +apiVersion: v1 +kind: Pod +metadata: + name: collector + namespace: nr-hcp-consul + labels: + app.kubernetes.io/name: collector +spec: + containers: + - name: collector + image: otel/opentelemetry-collector-contrib:0.98.0 + env: + # The default US endpoint is set here. You can change the endpoint and port based on your requirements if needed. + # docs: https://docs.newrelic.com/docs/more-integrations/open-source-telemetry-integrations/opentelemetry/best-practices/opentelemetry-otlp/#configure-endpoint-port-protocol + - name: NEW_RELIC_OTLP_ENDPOINT + value: https://otlp.nr-data.net/ + # The New Relic API key used to authenticate export requests. + # Defined in secrets.yaml + - name: NEW_RELIC_API_KEY + valueFrom: + secretKeyRef: + name: nr-hcp-consul-secret + key: NEW_RELIC_API_KEY + # The HCP Consul access token. + # Defined in secrets.yaml + - name: HCP_ACCESS_TOKEN + valueFrom: + secretKeyRef: + name: nr-hcp-consul-secret + key: HCP_ACCESS_TOKEN + # The HCP Consul access url. + # docs: https://developer.hashicorp.com/hcp/docs/consul/hcp-managed/access#get-access-url + - name: HCP_ACCESS_URL + value: + volumeMounts: + - name: collector-config-vol + mountPath: /etc/otelcol-contrib + volumes: + - name: collector-config-vol + configMap: + name: collector-config + items: + - key: collector-config + path: config.yaml diff --git a/other-examples/collector/hcp-consul/k8s/secrets.yaml b/other-examples/collector/hcp-consul/k8s/secrets.yaml new file mode 100644 index 00000000..533d27d7 --- /dev/null +++ b/other-examples/collector/hcp-consul/k8s/secrets.yaml @@ -0,0 +1,12 @@ +apiVersion: v1 +kind: Secret +metadata: + name: nr-hcp-consul-secret + namespace: nr-hcp-consul +stringData: + # New Relic API key to authenticate the export requests. + # docs: https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#license-key + NEW_RELIC_API_KEY: + # Set your HCP Access Token API Key. + # docs: https://developer.hashicorp.com/hcp/docs/consul/hcp-managed/access#generate-admin-token + HCP_ACCESS_TOKEN: