Add monograph usage reporting

Author: martinbonnin

CHANGELOG.md

@@ -3,7 +3,7 @@
 # Version 0.1.0
 _2024-10-23_
 
-* Add `apollo-execution-federation` with minimal `@key` support
+* Add `apollo-execution-subgraph` with minimal `@key` support
 * Add support for suspending resolvers and parallel execution (#18)
 * Update Ktor to version 3
 

Writerside/doc.tree

@@ -24,4 +24,7 @@
     <toc-element toc-title="Apollo Federation">
         <toc-element topic="federation.md"/>
     </toc-element>
+    <toc-element toc-title="Apollo Usage Reporting">
+        <toc-element topic="usage-reporting.md"/>
+    </toc-element>
 </instance-profile>

Writerside/topics/federation.md

@@ -2,16 +2,16 @@
 
 Apollo Kotlin Execution supports [Apollo Federation](https://www.apollographql.com/federation).
 
-To use federation, add the `apollo-execution-federation` artifact to your project:
+To use federation, add the `apollo-execution-subgraph` artifact to your project:
 
 ```kotlin
 dependencies {
   // Add the federation dependency
-  implementation("com.apollographql.execution:apollo-execution-federation:%latest_version%")
+  implementation("com.apollographql.execution:apollo-execution-subgraph:%latest_version%")
 }
 ```
 
-The `apollo-execution-federation` artifact contains the `@GraphQLKey` annotation allowing you to define [entities](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/intro).
+The `apollo-execution-subgraph` artifact contains the `@GraphQLKey` annotation allowing you to define [entities](https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/entities/intro).
 
 ## Defining entities
 
@@ -105,7 +105,10 @@ Apollo Kotlin Execution supports [federated tracing](https://www.apollographql.c
 
 Ftv1 records timing information for each field and reports that information to the router through the `"ftv1"` extension.
 
-This is done through the `Ftv1Instrumentation` and its matching `Ftv1Context`:
+> If you have a monograph, see [usage reporting](usage-reporting.md) instead for how to send tracing information to the Apollo usage reporting endpoint.
+{style=note}
+
+To enable federated tracing, configure your `ExecutableSchema` with a `Ftv1Instrumentation` and matching `Ftv1Context`:
 
 ```kotlin
 // Install the Ftv1Instrumentation in the executable schema

Writerside/topics/getting-started.md

@@ -11,6 +11,7 @@ Apollo Kotlin Execution:
 * Doesn't use reflection. Use it on the JVM and enjoy ultra-fast start times. Or use it with Kotlin native. Apollo Kotlin Execution is KMP-ready!
 * Supports custom scalars, subscriptions, persisted queries and everything in the current [GraphQL draft](https://spec.graphql.org/draft/).
 * Integrates with [Ktor](ktor.md), [http4k](http4k.md) and [Spring](spring.md).
+* Supports [Apollo Federation](federation.md).
 
 Under the hood, Apollo Kotlin Execution uses [KSP](https://kotlinlang.org/docs/ksp-overview.html) to generate GraphQL resolvers and types from your Kotlin code.
 

Writerside/topics/usage-reporting.md

@@ -0,0 +1,37 @@
+# Apollo Usage Reporting
+
+Apollo Kotlin Execution supports sending [operation and field reports](https://www.apollographql.com/docs/graphos/platform/insights/sending-operation-metrics) to GraphOS.
+
+> If you have a federated graph, see [ftv1](federation.md#tracing-ftv1) instead for how to send tracing information to the router.
+{style=note}
+
+## Sending usage reports
+
+Operation and field reports are sent using a protobuf protocol to `https://usage-reporting.api.apollographql.com/api/ingress/traces`.
+
+Apollo Kotlin collects, encodes and sends those reports using the `apollo-execution-reporting` artifact:
+
+```kotlin
+dependencies {
+  // Add the Apollo monograph artifact
+  implementation("com.apollographql.execution:apollo-execution-reporting:%latest_version%")
+}
+```
+
+To enable reports, configure your `ExecutableSchema` with a `ApolloReportsInstrumentation` and matching `ApolloReportsContext`:
+
+```kotlin
+// Get your API key from the environment or secret manager
+val apolloKey = System.getenv("APOLLO_KEY")
+
+// Install the ApolloReportsInstrumentation in the executable schema
+val schema = ServiceExecutableSchemaBuilder()
+    .addInstrumentation(ApolloReportsInstrumentation(apolloKey))
+    .build()
+
+// Create a new ApolloReportsContext() for each operation and use it through execution
+val reportsContext = ApolloReportsContext()
+val response = schema.execute(request, reportsContext)
+
+// The reports are sent in the background
+```

apollo-execution-federation/README.md

@@ -106,7 +106,7 @@ internal class ExecutableSchemaBuilderBuilder(
                   add(".addCoercing(%S, %M)\n", sirEnumDefinition.name, context.coercings.get(sirEnumDefinition.name))
                 }
                 if (entityResolver != null) {
-                  add(".addCoercing(%S, %M)\n", "_Any", MemberName("com.apollographql.execution.federation", "_AnyCoercing"))
+                  add(".addCoercing(%S, %M)\n", "_Any", MemberName("com.apollographql.execution.subgraph", "_AnyCoercing"))
                 }
                 listOf("query", "mutation", "subscription").forEach { operationType ->
                   val sirObjectDefinition = sirDefinitions.rootType(operationType)