Add tracing documentation and export tracing functions (#16)

* Add tracing documentation and export tracing functions

* Update changelog

Author: daniel-chambers

CHANGELOG.md

@@ -8,6 +8,7 @@ This changelog documents the changes between release versions.
 Changes to be included in the next upcoming release
 
 - Updated to [NDC TypeScript SDK v4.2.0](https://github.com/hasura/ndc-sdk-typescript/releases/tag/v4.2.0) to include OpenTelemetry improvements. Traced spans should now appear in the Hasura Console
+- Custom OpenTelemetry trace spans can now be emitted by creating an OpenTelemetry tracer and using it with `sdk.withActiveSpan` ([#16](https://github.com/hasura/ndc-nodejs-lambda/pull/16))
 
 ## [1.0.0] - 2024-02-22
 ### ndc-lambda-sdk

README.md

@@ -302,6 +302,34 @@ Descriptions are collected for:
 * Types
 * Type properties
 
+### Tracing
+Your functions are automatically instrumented with OpenTelemetry traces that Hasura will capture.
+
+By default, the following spans are emitted:
+* `handleQuery`/`handleMutation` - wraps the request from the Hasura DDN to the connector
+* `prepare arguments` - wraps the process of preparing arguments to pass to your function
+* `function invocation` - wraps a (potentially) parallel function invocation during a query
+* `Function: <function name>` - wraps the invocation of your function
+* `reshape result` - wraps the projection of the function result to match the requirements of the GraphQL selection set
+
+If you want to add additional spans around your own code, you can do so by using the OpenTelemetry SDK and `withActiveSpan` from `ndc-lambda-sdk`:
+
+```typescript
+import opentelemetry from '@opentelemetry/api';
+import * as sdk from "@hasura/ndc-lambda-sdk"
+
+const tracer = opentelemetry.trace.getTracer("my functions"); // Name your functions service here
+
+export async function doSomething(): Promise<string> {
+  const spanAttributes = { myAttribute: "value" };
+  return await sdk.withActiveSpan(tracer, "my span name", async () => {
+    return await doSomethingExpensive();
+  }, spanAttributes);
+}
+```
+
+The span will be wrapped around the function you pass to `sdk.withActiveSpan`. The function can optionally be an async function that returns a Promise, and if so, the span will be ended when the Promise resolves.
+
 ## Deploying with `hasura3 connector create`
 
 You will need:

ndc-lambda-sdk/src/sdk.ts

@@ -1,3 +1,4 @@
 export { JSONValue } from "./schema";
 export { ConnectorError, BadRequest, Forbidden, Conflict, UnprocessableContent, InternalServerError, NotSupported, BadGateway } from "@hasura/ndc-sdk-typescript";
+export { withActiveSpan, USER_VISIBLE_SPAN_ATTRIBUTE } from "@hasura/ndc-sdk-typescript/instrumentation"
 export { ErrorDetails, getErrorDetails } from "./execution";