apollo-reporting-protobuf

What is apollo-reporting-protobuf?

The apollo-reporting-protobuf package is designed for use with Apollo GraphQL services. It provides functionality for generating, serializing, and deserializing Protocol Buffers (protobuf) definitions related to Apollo's usage reporting. This is particularly useful for Apollo Server operators who want to send detailed performance metrics and usage information to Apollo Studio in a highly efficient and compact format.

What are apollo-reporting-protobuf's main functionalities?

Generating Trace Reports

This feature allows you to generate trace reports for individual operations. These traces can include detailed performance metrics, such as resolver execution times, which are useful for debugging and optimization.

const { Trace } = require('apollo-reporting-protobuf');
const trace = new Trace();
trace.startTime = Date.now();
// Populate trace with details of the operation
trace.endTime = Date.now();

Serializing Trace Reports

This feature enables the serialization of trace reports into a compact binary format using Protocol Buffers. This is useful for efficiently transmitting data to Apollo Studio or other analysis tools.

const { Trace } = require('apollo-reporting-protobuf');
const trace = new Trace();
// Assume trace is populated
const serializedTrace = Trace.encode(trace).finish();

Deserializing Trace Reports

This feature allows for the deserialization of previously serialized trace reports. This is useful for analyzing or processing trace data received in a compact binary format.

const { Trace } = require('apollo-reporting-protobuf');
const serializedTrace = /* binary data */;
const trace = Trace.decode(serializedTrace);

Other packages similar to apollo-reporting-protobuf

protobufjs

protobufjs is a more general-purpose package for working with Protocol Buffers in JavaScript. Unlike apollo-reporting-protobuf, which is tailored specifically for Apollo's usage reporting, protobufjs provides a broader set of tools for defining, serializing, and deserializing protobufs. It can be used for a wide range of applications beyond GraphQL reporting.

README

apollo-reporting-protobuf

Note: The Apollo usage reporting API is subject to change. We strongly encourage developers to contact Apollo support at [e-mail] to discuss their use case prior to building their own reporting agent using this module.

This module provides JavaScript/TypeScript Protocol buffer definitions for the Apollo usage reporting API. These definitions are generated for consumption from the reports.proto file which is defined internally within Apollo.

Development

Note: Due to a dependency on Unix tools (e.g. bash, grep, etc.), the development of this module requires a Unix system. There is no reason why this can't be avoided, the time just hasn't been taken to make those changes. We'd happily accept a PR which makes the appropriate changes!

Currently, this package generates a majority of its code with @apollo/protobufjs (a fork of protobufjs that we maintain specifically for this package) based on the reports.proto file. The output is generated with the generate npm script.

The root of the repository provides some devDependencies necessary to build these definitions and the prepare npm script is invoked programmatically via the monorepo tooling (e.g. Lerna) thanks to this module's postinstall script. Therefore, when making changes to this module, run scripts via npx lerna run SCRIPTNAME in the root of this monorepo in order to update the definitions in this module.

To update reports.proto to the current version recognized by the Studio usage reporting ingress, run lerna run update-proto. To then regenerate the JS and TS files, run npx lerna run generate. We check in the generated code and only regenerate it manually, partially to make builds faster (no need to run pbjs on every npm install) and partially so that we don't have to make sure that pbjs runs on every Node version that we support.