newrelic / newrelic-telemetry-sdk-c

C library for sending telemetry data to New Relic

Archival Notice

As of August 2023, The New Relic C Telemetry SDK is archived.

New Relic C Telemetry SDK

What is the New Relic C Telemetry SDK?

• It's a helper library that supports sending New Relic data from within your C/C++ application.
• It’s an example of "best practices" for sending us data.

The Telemetry SDK provides you, the end-user programmer, with a Client that sends Spans to New Relic. Individual spans are collected together into batches (via a SpanBatch object), and clients send these batches. It serves as a foundation for getting open-standards based telemetry data like OpenCensus, OpenTracing, and OpenTelemetry into New Relic. You can use this to build tracers/exporters, such as ones based on these open standards.

This SDK currently supports sending spans to the Trace API.

Requirements

The C Telemetry SDK is a wrapper around the Rust Telemetry SDK. Minimal build requirements are:

• CMake 3.0
• Rust 1.44

For running tests under Linux, valgrind is required.

The C Telemetry SDK aims to support any platform that is supported by Rust. It was tested on 64 bit Linux (GNU GCC 7.5), and on 64 bit Windows 2019 (Visual Studio 2019).

Building the C Telemetry SDK

The Rust Telemetry SDK is included into this project as a git submodule. Before building the C Telemetry SDK, make sure git submodules are initialized by running this command:

git submodule update --init

Linux

For building the C Telemetry SDK on Linux, run the following commands:

mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make

To build and run tests:

mkdir build && cd build
cmake -DENABLE_TESTS=on ..
make
make test

Windows

For building the C Telemetry SDK on Windows, run the following commands:

mkdir build
cd build
cmake ..
cmake --build .

Getting Started

In order to send telemetry data to New Relic APIs, you will need an Insert API key. to find out how to generate this key, see our docs.

Refer to the API documentation and to the examples.

This is a simple application that sends a single span:

#include "newrelic-telemetry-sdk.h"
#include <stdio.h>
#include <stdlib.h>
#ifdef OS_WINDOWS
#include <windows.h>
#else
#include <sys/time.h>
#endif

int main() {

  /* Obtain an API key from the environment. */
  const char* api_key = getenv("NEW_RELIC_API_KEY");
  if (!api_key) {
    fprintf(stderr, "NEW_RELIC_API_KEY not set\n");
    exit(1);
  }

  /* Initialize a configuration. */
  nrt_client_config_t* cfg = nrt_client_config_new(api_key);

  /* Initialize a new client with the given API key. */
  nrt_client_t* client = nrt_client_new(&cfg);

  /* Create an empty span batch */
  nrt_span_batch_t* batch = nrt_span_batch_new();

  /* Create a span and add it to the batch */
  {
#ifdef OS_WINDOWS
    SYSTEMTIME time;
    GetSystemTime(&time);
    nrt_time_t time_ms = (time.wSecond * 1000) + time.wMilliseconds;
#else
    struct timeval tv;
    gettimeofday(&tv, NULL);
    nrt_time_t time_ms = (tv.tv_sec) * 1000 + (tv.tv_usec) / 1000;
#endif

    nrt_span_t* span
        = nrt_span_new("e9f54a2c322d7578", "1b1bf29379951c1d", time_ms);
    nrt_span_set_name(span, "/index.html");
    nrt_span_set_duration(span, 2000);
    nrt_span_set_service_name(span, "Telemetry Application");

    nrt_attributes_t* attrs = nrt_attributes_new();
    nrt_attributes_set_int(attrs, "retries", 3);
    nrt_attributes_set_string(attrs, "username", "user");
    nrt_span_set_attributes(span, &attrs);

    nrt_span_batch_record(batch, &span);
  }

  /* Queue the span batch */
  nrt_client_send(client, &batch);

  /* Wait for the batch to be sent and shut down the client. */
  nrt_client_shutdown(&client);
}

Find and use your data

Tips on how to find and query your data in New Relic:

• Find trace/span data

For general querying information, see:

• Query New Relic data
• Intro to NRQL

Support

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. Like all official New Relic open source projects, there's a related Community topic in the New Relic Explorers Hub. You can find this project's topic/threads in the Telemetry SDK section of Explorers Hub

License

The C Telemetry SDK is licensed under the Apache 2.0 License.

The C Telemetry SDK also uses source code from third-party libraries. You can find full details on which libraries are used and the terms under which they are licensed in the third-party notices document.

Limitations

The New Relic Telemetry APIs are rate limited. Please reference the documentation for New Relic Metric API and New Relic Trace API requirements and limits on the specifics of the rate limits.

newrelic-telemetry-sdk-c's Issues

Wrap the sender functions

Wrap the Sender functions found in the Rust Telemetry SDK. #4 can be used as a template to accomplish this. Include an example to test each of the wrapped functions.

Implement a mechanism for configuration

Currently, by just wrapping the newrelic-telemetry-sdk-rust crate, we have no mechanism for configuration on the c-side other than passing variables to the initializing functions.

For this issue, implement a configuration system that, from a file or environment variable (with the latter having a higher override precedence), loads the API key, log level (depends on #5), and any other relevant options.

Go through open source checklist

We need to go through the NR open source checklist to ensure this repo is ready to be open-sourced.

Update documentation

The documentation in this repo needs to be updated. Currently, the README is a template document and needs specific updates reflecting our work with the telemetry SDK. Also, we need to ensure that the ThirdPartyNotices and Contributing docs reflect accurate information. Please take time to ensure these public-facing documentation are ready to be viewed once this repo is open-sourced.

Wrap span functions

Wrap the span functions in the Rust Telemetry SDK. #4 can be used as a template to accomplish this. Include an example to test each of the wrapped functions.

Create C API design/example

Open a pull request indicating the proposed C API as either a c .h header file, or as markdown documentation.

All engineers must review and approve this proposal prior to merging

Ensure all wrapped functions are tested

Ensure all the wrapped functions are tested and that a span batch is sent all the way through to the endpoint. Examples should have been included with the wrapped function PRs, so this might just be a verification ticket to ensure all functions are covered. If any gaps are found, add them to existing examples.

Hook up the rust repo and wrap the attribute functions

We need to hook up the newrelic-telemetry-sdk-rust repo, and use it to implement wrappers for nrt_attribute_* functions.

At the final stage, we'll be able to use the newrelic-telemetry crate directly from crates.io. Until we will be able to publish and use this crate, we should use git submodules.

Fix example link the API documentation

The examples link in the API documentation needs to be fixed. The API documentation is created automatically using the README and did not convert the examples link correctly in the Getting Started section. You can see below, the [examples](examples) should be examples.

Getting Started
In order to send telemetry data to New Relic APIs, you will need an Insert API key. to find out how to generate this key, see our docs.

Refer to the API documentation and to the [examples](examples).

This is a simple application that sends a single span:

Add API documentation

We need to add API documentation using GitHub pages. This should be done using Doxygen and be added to the GitHub actions CI to ensure automation.

Add attributes to the span

#17 adds the functionality to wrap all the span functions with the exception of attributes. Now we need to be able to add attributes to the span attributes hashmap.

Add copyright block to source files

The below copyright block needs to be added to all source (.c, .h, and .rs.) files.

For .c and .h files

/*
 * Copyright 2020 New Relic Corporation. All rights reserved.
 * SPDX-License-Identifier: Apache-2.0
 */

For .rs files

///
/// Copyright 2020 New Relic Corporation. All rights reserved.
/// SPDX-License-Identifier: Apache-2.0
///

Wrap span batch functions

Wrap the span batch functions found in the Rust Telemetry SDK. #4 can be used as a template to accomplish this. Include an example to test each of the wrapped functions.

The verbosity and the destination of the log must be configurable.

According to the newrelic-telemetry-sdk-specs regarding logging,

SDK implementations should log troubleshooting and error information 
by whatever means is the most idiomatic for the language. SDKs must 
provide a mechanism to configure the destination and verbosity of the log, 
and a way to disable the SDK's logging.

When enabled, SDKs should primarily use three logging levels: 
ERROR,INFO, DEBUG, with DEBUG being the most verbose and 
ERROR the least.

Additionally,

If audit logging is enabled in the SDK configuration, 
additional highly verbose debugging information should 
be logged at the DEBUG level

The newrelic-telemetry-sdk-c needs to provide a way to configure log location and level.

One option would be to make the file and log level configurable via the API. Another option would be to use the env_logger crate, and let the user specify the log location via an environment variable.