@graphql-yoga/plugin-apollo-usage-report 0.13.0 → 0.13.1-alpha-20260116132159-d18a95d04a1e11d197fdf672a8be4836ceed0818

package/typings/index.d.ts

@@ -1,122 +0,0 @@
-import { YogaLogger, YogaServer, type Maybe, type Plugin, type YogaInitialContext } from 'graphql-yoga';
-import { calculateReferencedFieldsByType } from '@apollo/utils.usagereporting';
-import { ApolloInlineGraphqlTraceContext, ApolloInlineRequestTraceContext, ApolloInlineTracePluginOptions } from '@graphql-yoga/plugin-apollo-inline-trace';
-import { Reporter } from './reporter.js';
-export type ApolloUsageReportOptions = ApolloInlineTracePluginOptions & {
-    /**
-     * The graph ref of the managed federation graph.
-     * It is composed of the graph ID and the variant (`<YOUR_GRAPH_ID>@<VARIANT>`).
-     *
-     * If not provided, `APOLLO_GRAPH_REF` environment variable is used.
-     *
-     * You can find a a graph's ref at the top of its Schema Reference page in Apollo Studio.
-     */
-    graphRef?: string;
-    /**
-     * The API key to use to authenticate with the managed federation up link.
-     * It needs at least the `service:read` permission.
-     *
-     * If not provided, `APOLLO_KEY` environment variable will be used instead.
-     *
-     * [Learn how to create an API key](https://www.apollographql.com/docs/federation/v1/managed-federation/setup#4-connect-the-gateway-to-studio)
-     */
-    apiKey?: string;
-    /**
-     * Usage report endpoint
-     *
-     * Defaults to GraphOS endpoint (https://usage-reporting.api.apollographql.com/api/ingress/traces)
-     */
-    endpoint?: string;
-    /**
-     * Agent Version to report to the usage reporting API
-     */
-    agentVersion?: string;
-    /**
-     * Client name to report to the usage reporting API
-     */
-    clientName?: StringFromRequestFn;
-    /**
-     * Client version to report to the usage reporting API
-     */
-    clientVersion?: StringFromRequestFn;
-    /**
-     * The version of the runtime (like 'node v23.7.0')
-     * @default empty string.
-     */
-    runtimeVersion?: string;
-    /**
-     * The hostname of the machine running this server
-     * @default $HOSTNAME environment variable
-     */
-    hostname?: string;
-    /**
-     * The OS identification string.
-     * The format is `${os.platform()}, ${os.type()}, ${os.release()}, ${os.arch()})`
-     * @default empty string
-     */
-    uname?: string;
-    /**
-     * The maximum estimated size of each traces in bytes. If the estimated size is higher than this threshold,
-     * the complete trace will not be sent and will be reduced to aggregated stats.
-     *
-     * Note: GraphOS only allow for traces of 10mb maximum
-     * @default 10 * 1024 * 1024 (10mb)
-     */
-    maxTraceSize?: number;
-    /**
-     * The maximum uncompressed size of a report in bytes.
-     * The report will be sent once this threshold is reached, even if the delay between send is not
-     * yet expired.
-     *
-     * @default 4Mb
-     */
-    maxBatchUncompressedSize?: number;
-    /**
-     * The maximum time in ms between reports.
-     * @default 20s
-     */
-    maxBatchDelay?: number;
-    /**
-     * Control if traces should be always sent.
-     * If false, the traces will be batched until a delay or size is reached.
-     * Note: This is highly not recommended in a production environment
-     *
-     * @default false
-     */
-    alwaysSend?: boolean;
-    /**
-     * Timeout in ms of a trace export tentative
-     * @default 30s
-     */
-    exportTimeout?: number;
-    /**
-     * The class to be used to keep track of traces and send them to the GraphOS endpoint
-     * Note: This option is aimed to be used for testing purposes
-     */
-    reporter?: (options: ApolloUsageReportOptions, yoga: YogaServer<Record<string, unknown>, Record<string, unknown>>, logger: YogaLogger) => Reporter;
-    /**
-     * Called when all retry attempts to send a report to GraphOS endpoint failed.
-     * By default, the error is logged.
-     */
-    onError?: (err: Error) => void;
-    /**
-     * If false, unexecutable operation (with parsing or validation error) will not be sent
-     * @default false
-     */
-    sendUnexecutableOperationDocuments?: boolean;
-};
-export interface ApolloUsageReportRequestContext extends ApolloInlineRequestTraceContext {
-    traces: Map<YogaInitialContext, ApolloUsageReportGraphqlContext>;
-}
-export interface ApolloUsageReportGraphqlContext extends ApolloInlineGraphqlTraceContext {
-    referencedFieldsByType?: ReturnType<typeof calculateReferencedFieldsByType>;
-    operationKey?: string;
-    schemaId?: string;
-}
-type StringFromRequestFn = (req: Request) => Maybe<string>;
-export declare function useApolloUsageReport(options?: ApolloUsageReportOptions): Plugin;
-export declare function hashSHA256(text: string, api?: {
-    crypto: Crypto;
-    TextEncoder: (typeof globalThis)['TextEncoder'];
-}): Promise<string>;
-export {};

package/typings/reporter.d.cts

@@ -1,21 +0,0 @@
-import { YogaLogger, YogaServer } from 'graphql-yoga';
-import { google } from '@apollo/usage-reporting-protobuf';
-import type { ApolloUsageReportOptions } from './index';
-import { OurReport } from './stats.cjs';
-export declare class Reporter {
-    private yoga;
-    private logger;
-    private reportHeaders;
-    private options;
-    private reportsBySchema;
-    private nextSendAfterDelay?;
-    private sending;
-    constructor(options: ApolloUsageReportOptions, yoga: YogaServer<Record<string, unknown>, Record<string, unknown>>, logger: YogaLogger);
-    addTrace(schemaId: string, options: Parameters<OurReport['addTrace']>[0]): Promise<void> | undefined;
-    flush(): Promise<PromiseSettledResult<unknown>[]>;
-    sendReport(schemaId: string): Promise<void>;
-    private _sendReport;
-    private getReport;
-}
-export declare function getEnvVar<T>(name: string, defaultValue?: T): string | T | undefined;
-export declare function dateToProtoTimestamp(date: Date): google.protobuf.Timestamp;

package/typings/reporter.d.ts

@@ -1,21 +0,0 @@
-import { YogaLogger, YogaServer } from 'graphql-yoga';
-import { google } from '@apollo/usage-reporting-protobuf';
-import type { ApolloUsageReportOptions } from './index';
-import { OurReport } from './stats.js';
-export declare class Reporter {
-    private yoga;
-    private logger;
-    private reportHeaders;
-    private options;
-    private reportsBySchema;
-    private nextSendAfterDelay?;
-    private sending;
-    constructor(options: ApolloUsageReportOptions, yoga: YogaServer<Record<string, unknown>, Record<string, unknown>>, logger: YogaLogger);
-    addTrace(schemaId: string, options: Parameters<OurReport['addTrace']>[0]): Promise<void> | undefined;
-    flush(): Promise<PromiseSettledResult<unknown>[]>;
-    sendReport(schemaId: string): Promise<void>;
-    private _sendReport;
-    private getReport;
-}
-export declare function getEnvVar<T>(name: string, defaultValue?: T): string | T | undefined;
-export declare function dateToProtoTimestamp(date: Date): google.protobuf.Timestamp;

package/typings/stats.d.cts

@@ -1,136 +0,0 @@
-import type { NonFtv1ErrorPath } from '@apollo/server-gateway-interface';
-import { Trace, type google, type IContextualizedStats, type IFieldStat, type IPathErrorStats, type IQueryLatencyStats, type IReport, type IStatsContext, type ITracesAndStats, type ITypeStat, type ReportHeader } from '@apollo/usage-reporting-protobuf';
-import type { ReferencedFieldsByType } from '@apollo/utils.usagereporting';
-export declare class SizeEstimator {
-    bytes: number;
-}
-export declare class OurReport implements Required<IReport> {
-    readonly header: ReportHeader;
-    tracesPreAggregated: boolean;
-    constructor(header: ReportHeader);
-    readonly tracesPerQuery: Record<string, OurTracesAndStats>;
-    endTime: google.protobuf.ITimestamp | null;
-    operationCount: number;
-    readonly sizeEstimator: SizeEstimator;
-    ensureCountsAreIntegers(): void;
-    addTrace({ statsReportKey, trace, asTrace, referencedFieldsByType, maxTraceBytes, nonFtv1ErrorPaths, }: {
-        statsReportKey: string;
-        trace: Trace;
-        asTrace: boolean;
-        referencedFieldsByType: ReferencedFieldsByType;
-        maxTraceBytes?: number;
-        nonFtv1ErrorPaths: NonFtv1ErrorPath[];
-    }): void;
-    private getTracesAndStats;
-}
-declare class OurTracesAndStats implements Required<ITracesAndStats> {
-    readonly referencedFieldsByType: ReferencedFieldsByType;
-    constructor(referencedFieldsByType: ReferencedFieldsByType);
-    readonly trace: Uint8Array[];
-    readonly statsWithContext: StatsByContext;
-    readonly internalTracesContributingToStats: Uint8Array[];
-    ensureCountsAreIntegers(): void;
-}
-declare class StatsByContext {
-    readonly map: {
-        [k: string]: OurContextualizedStats;
-    };
-    /**
-     * This function is used by the protobuf generator to convert this map into
-     * an array of contextualized stats to serialize
-     */
-    toArray(): IContextualizedStats[];
-    ensureCountsAreIntegers(): void;
-    addTrace(trace: Trace, sizeEstimator: SizeEstimator, nonFtv1ErrorPaths: NonFtv1ErrorPath[]): void;
-    private getContextualizedStats;
-}
-export declare class OurContextualizedStats implements Required<IContextualizedStats> {
-    readonly context: IStatsContext;
-    queryLatencyStats: OurQueryLatencyStats;
-    perTypeStat: {
-        [k: string]: OurTypeStat;
-    };
-    constructor(context: IStatsContext);
-    ensureCountsAreIntegers(): void;
-    addTrace(trace: Trace, sizeEstimator: SizeEstimator, nonFtv1ErrorPaths?: NonFtv1ErrorPath[]): void;
-    getTypeStat(parentType: string, sizeEstimator: SizeEstimator): OurTypeStat;
-}
-declare class OurQueryLatencyStats implements Required<IQueryLatencyStats> {
-    latencyCount: DurationHistogram;
-    requestCount: number;
-    requestsWithoutFieldInstrumentation: number;
-    cacheHits: number;
-    persistedQueryHits: number;
-    persistedQueryMisses: number;
-    cacheLatencyCount: DurationHistogram;
-    rootErrorStats: OurPathErrorStats;
-    requestsWithErrorsCount: number;
-    publicCacheTtlCount: DurationHistogram;
-    privateCacheTtlCount: DurationHistogram;
-    registeredOperationCount: number;
-    forbiddenOperationCount: number;
-}
-declare class OurPathErrorStats implements Required<IPathErrorStats> {
-    children: {
-        [k: string]: OurPathErrorStats;
-    };
-    errorsCount: number;
-    requestsWithErrorsCount: number;
-    getChild(subPath: string, sizeEstimator: SizeEstimator): OurPathErrorStats;
-}
-declare class OurTypeStat implements Required<ITypeStat> {
-    perFieldStat: {
-        [k: string]: OurFieldStat;
-    };
-    getFieldStat(fieldName: string, returnType: string, sizeEstimator: SizeEstimator): OurFieldStat;
-    ensureCountsAreIntegers(): void;
-}
-declare class OurFieldStat implements Required<IFieldStat> {
-    readonly returnType: string;
-    errorsCount: number;
-    observedExecutionCount: number;
-    estimatedExecutionCount: number;
-    requestsWithErrorsCount: number;
-    latencyCount: DurationHistogram;
-    constructor(returnType: string);
-    ensureCountsAreIntegers(): void;
-}
-export interface DurationHistogramOptions {
-    initSize?: number;
-    buckets?: number[];
-}
-export declare class DurationHistogram {
-    private readonly buckets;
-    static readonly BUCKET_COUNT = 384;
-    static readonly EXPONENT_LOG: number;
-    toArray(): number[];
-    static durationToBucket(durationNs: number): number;
-    incrementDuration(durationNs: number, value?: number): DurationHistogram;
-    incrementBucket(bucket: number, value?: number): void;
-    combine(otherHistogram: DurationHistogram): void;
-    constructor(options?: DurationHistogramOptions);
-}
-/**
- * Iterates over the entire trace, calling `f` on each Trace.Node found. It
- * looks under the "root" node as well as any inside the query plan. If any `f`
- * returns true, it stops walking the tree.
- *
- * Each call to `f` will receive an object that implements ResponseNamePath. If
- * `includePath` is true, `f` can call `toArray()` on it to convert the
- * linked-list representation to an array of the response name (field name)
- * nodes that you navigate to get to the node (including a "service:subgraph"
- * top-level node if this is a federated trace). Note that we don't add anything
- * to the path for index (list element) nodes. This is because the only use case
- * we have (error path statistics) does not care about list indexes (it's not
- * that interesting to know that sometimes an error was at foo.3.bar and
- * sometimes foo.5.bar, vs just generally foo.bar).
- *
- * If `includePath` is false, we don't bother to build up the linked lists, and
- * calling `toArray()` will throw.
- */
-export declare function iterateOverTrace(trace: Trace, f: (node: Trace.INode, path: ResponseNamePath) => boolean, includePath: boolean): void;
-export interface ResponseNamePath {
-    toArray(): string[];
-    child(responseName: string): ResponseNamePath;
-}
-export {};

package/typings/stats.d.ts

@@ -1,136 +0,0 @@
-import type { NonFtv1ErrorPath } from '@apollo/server-gateway-interface';
-import { Trace, type google, type IContextualizedStats, type IFieldStat, type IPathErrorStats, type IQueryLatencyStats, type IReport, type IStatsContext, type ITracesAndStats, type ITypeStat, type ReportHeader } from '@apollo/usage-reporting-protobuf';
-import type { ReferencedFieldsByType } from '@apollo/utils.usagereporting';
-export declare class SizeEstimator {
-    bytes: number;
-}
-export declare class OurReport implements Required<IReport> {
-    readonly header: ReportHeader;
-    tracesPreAggregated: boolean;
-    constructor(header: ReportHeader);
-    readonly tracesPerQuery: Record<string, OurTracesAndStats>;
-    endTime: google.protobuf.ITimestamp | null;
-    operationCount: number;
-    readonly sizeEstimator: SizeEstimator;
-    ensureCountsAreIntegers(): void;
-    addTrace({ statsReportKey, trace, asTrace, referencedFieldsByType, maxTraceBytes, nonFtv1ErrorPaths, }: {
-        statsReportKey: string;
-        trace: Trace;
-        asTrace: boolean;
-        referencedFieldsByType: ReferencedFieldsByType;
-        maxTraceBytes?: number;
-        nonFtv1ErrorPaths: NonFtv1ErrorPath[];
-    }): void;
-    private getTracesAndStats;
-}
-declare class OurTracesAndStats implements Required<ITracesAndStats> {
-    readonly referencedFieldsByType: ReferencedFieldsByType;
-    constructor(referencedFieldsByType: ReferencedFieldsByType);
-    readonly trace: Uint8Array[];
-    readonly statsWithContext: StatsByContext;
-    readonly internalTracesContributingToStats: Uint8Array[];
-    ensureCountsAreIntegers(): void;
-}
-declare class StatsByContext {
-    readonly map: {
-        [k: string]: OurContextualizedStats;
-    };
-    /**
-     * This function is used by the protobuf generator to convert this map into
-     * an array of contextualized stats to serialize
-     */
-    toArray(): IContextualizedStats[];
-    ensureCountsAreIntegers(): void;
-    addTrace(trace: Trace, sizeEstimator: SizeEstimator, nonFtv1ErrorPaths: NonFtv1ErrorPath[]): void;
-    private getContextualizedStats;
-}
-export declare class OurContextualizedStats implements Required<IContextualizedStats> {
-    readonly context: IStatsContext;
-    queryLatencyStats: OurQueryLatencyStats;
-    perTypeStat: {
-        [k: string]: OurTypeStat;
-    };
-    constructor(context: IStatsContext);
-    ensureCountsAreIntegers(): void;
-    addTrace(trace: Trace, sizeEstimator: SizeEstimator, nonFtv1ErrorPaths?: NonFtv1ErrorPath[]): void;
-    getTypeStat(parentType: string, sizeEstimator: SizeEstimator): OurTypeStat;
-}
-declare class OurQueryLatencyStats implements Required<IQueryLatencyStats> {
-    latencyCount: DurationHistogram;
-    requestCount: number;
-    requestsWithoutFieldInstrumentation: number;
-    cacheHits: number;
-    persistedQueryHits: number;
-    persistedQueryMisses: number;
-    cacheLatencyCount: DurationHistogram;
-    rootErrorStats: OurPathErrorStats;
-    requestsWithErrorsCount: number;
-    publicCacheTtlCount: DurationHistogram;
-    privateCacheTtlCount: DurationHistogram;
-    registeredOperationCount: number;
-    forbiddenOperationCount: number;
-}
-declare class OurPathErrorStats implements Required<IPathErrorStats> {
-    children: {
-        [k: string]: OurPathErrorStats;
-    };
-    errorsCount: number;
-    requestsWithErrorsCount: number;
-    getChild(subPath: string, sizeEstimator: SizeEstimator): OurPathErrorStats;
-}
-declare class OurTypeStat implements Required<ITypeStat> {
-    perFieldStat: {
-        [k: string]: OurFieldStat;
-    };
-    getFieldStat(fieldName: string, returnType: string, sizeEstimator: SizeEstimator): OurFieldStat;
-    ensureCountsAreIntegers(): void;
-}
-declare class OurFieldStat implements Required<IFieldStat> {
-    readonly returnType: string;
-    errorsCount: number;
-    observedExecutionCount: number;
-    estimatedExecutionCount: number;
-    requestsWithErrorsCount: number;
-    latencyCount: DurationHistogram;
-    constructor(returnType: string);
-    ensureCountsAreIntegers(): void;
-}
-export interface DurationHistogramOptions {
-    initSize?: number;
-    buckets?: number[];
-}
-export declare class DurationHistogram {
-    private readonly buckets;
-    static readonly BUCKET_COUNT = 384;
-    static readonly EXPONENT_LOG: number;
-    toArray(): number[];
-    static durationToBucket(durationNs: number): number;
-    incrementDuration(durationNs: number, value?: number): DurationHistogram;
-    incrementBucket(bucket: number, value?: number): void;
-    combine(otherHistogram: DurationHistogram): void;
-    constructor(options?: DurationHistogramOptions);
-}
-/**
- * Iterates over the entire trace, calling `f` on each Trace.Node found. It
- * looks under the "root" node as well as any inside the query plan. If any `f`
- * returns true, it stops walking the tree.
- *
- * Each call to `f` will receive an object that implements ResponseNamePath. If
- * `includePath` is true, `f` can call `toArray()` on it to convert the
- * linked-list representation to an array of the response name (field name)
- * nodes that you navigate to get to the node (including a "service:subgraph"
- * top-level node if this is a federated trace). Note that we don't add anything
- * to the path for index (list element) nodes. This is because the only use case
- * we have (error path statistics) does not care about list indexes (it's not
- * that interesting to know that sometimes an error was at foo.3.bar and
- * sometimes foo.5.bar, vs just generally foo.bar).
- *
- * If `includePath` is false, we don't bother to build up the linked lists, and
- * calling `toArray()` will throw.
- */
-export declare function iterateOverTrace(trace: Trace, f: (node: Trace.INode, path: ResponseNamePath) => boolean, includePath: boolean): void;
-export interface ResponseNamePath {
-    toArray(): string[];
-    child(responseName: string): ResponseNamePath;
-}
-export {};