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.
apollo-reporting-protobuf
Note: The Apollo usage reporting API is subject to change. We strongly
encourage developers to contact Apollo support at support@apollographql.com
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
protobufjs
based on the
reports.proto
file. The output is generated with the prepare
npm script.
The root of the repository provides the devDependencies
necessary to build
these definitions (e.g. pbjs
, pbts
, protobuf
, etc.) 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, npx lerna run prepare
should be run from the root
of this monorepo in order to update the definitions in this module.