![\"Digital](\"https:\/\/images.unsplash.com\/photo-1762330470070-249e7c23c8c0?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixid=M3w4NDY5MTd8MHwxfHNlYXJjaHwxfHxXaGF0JTIweW91JUUyJTgwJTk5bGwlMjBidWlsZCUwQVlvdSUyMGFscmVhZHklMjBtb3ZlJTIwZmFzdCUyMHdpdGglMjBOaG9zdCUzQSUyMFBvc3RncmVzJTJDJTIwcmVhbC10aW1lJTIwR3JhcGhRTCUyQyUyMEF1dGhlbnRpY2F0aW9uJTJDJTIwU3RvcmFnZSUyQyUyMGFuZCUyMFNlcnZlcmxlc3MlMjBGdW5jdGlvbnMlMjB3aXRob3V0JTIwdG91Y2hpbmclMjBzZXJ2ZXJzLiUyME5vdyUyMHlvdSUyMGNhbiUyMGFkZCUyMG9ic2VydmFiaWxpdHklMjBhbmQlMjBtb25pdG9yaW5nJTIwdGhhdCUyMGlzJTIwanVzdCUyMGFzJTIwZmFzdC4lMjBJbiUyMHRoaXMlMjBndWlkZSUyQyUyMHlvdSVFMiU4MCU5OWxsJTIwc2V0JTIwdXAlMjBhJTIwdmVuZG9yLW5ldXRyYWwlMjBPcGVuVGVsZW1ldHJ5JTIwcGlwZWxpbmUlMjBzbyUyMHlvdXIlMjBOaG9zdCUyMEdyYXBoUUwlMjBBUEklMjBhbmQlMjBGdW5jdGlvbnMlMjBlbWl0JTIwdHJhY2VzJTJDJTIwbG9ncyUyMGFuZCUyMG1ldHJpY3MlMjB0byUyMHlvdXIlMjBPcGVuVGVsZW1ldHJ5JTIwQ29sbGVjdG9yJTIwYW5kJTIwdmlzdWFsaXphdGlvbiUyMHRvb2wlMjBvZiUyMGNob2ljZS4lMjBZb3UlRTIlODAlOTlsbCUyMHNlZSUyMG9uZSUyMGNvaGVyZW50JTJDJTIwZW5kLXRvLWVuZCUyMHRyYWNlJTIwdGhhdCUyMGZsb3dzJTIwYWNyb3NzJTIwR3JhcGhRTCUyMHJlc29sdmVycyUyQyUyMEFjdGlvbnMlMkMlMjBFdmVudCUyMFRyaWdnZXJzJTJDJTIwRnVuY3Rpb25zJTJDJTIwUG9zdGdyZXMlMjB0aW1pbmdzJTJDJTIwQXV0aCUyMHdlYmhvb2tzJTJDJTIwU3RvcmFnZSUyMG9wZXJhdGlvbnMlMkMlMjBhbmQlMjBldmVuJTIwQnJpbmclMjBZb3VyJTIwT3duJTIwQ29udGFpbmVycyUyMCUyOEJZT0MlMjklMjBzZXJ2aWNlcyVFMiU4MCU5NHdpdGhvdXQlMjBtYW5hZ2luZyUyMGFueSUyMGluZnJhc3RydWN0dXJlJTIwb24lMjB5b3VyJTIwb3duLiUwQVRoZSUyMHJlc3VsdCUzQSUyMHJlbGlhYmxlJTIwTmhvc3QlMjBtb25pdG9yaW5nJTIwYW5kJTIwcGVyZm9ybWFuY2UlMjBtb25pdG9yaW5nJTIwd2l0aCUyMHNlcnZpY2UlMjBncmFwaHMlMjB0aGF0JTIwbWFrZSUyMHNlbnNlJTJDJTIwYWxlcnRpbmclMjB0aGF0JTIwY2F0Y2hlcyUyMHJlYWwlMjBwcm9ibGVtcyUyQyUyMGFuZCUyMGRhc2hib2FyZHMlMjB0aGF0JTIwZXhwbGFpbiUyMCVFMiU4MCU5Q3doeSVFMiU4MCU5RCUyMHdoZW4lMjBsYXRlbmN5JTIwc3Bpa2VzJTIwb3IlMjBlcnJvciUyMHJhdGVzJTIwY3JlZXAlMjB1cC4lMEElMEFSZWZlcmVuY2UlMjBhcmNoaXRlY3R1cmV8ZW58MHwwfHx8MTc4Mzk1Njc3OXww&ixlib=rb-4.1.0&q=80&w=1080\")
The architecture is intentionally simple and portable. Nhost services export OpenTelemetry signals over OTLP\/HTTPS to an internet-accessible Collector that fans out to your preferred backends (Grafana Tempo\/Loki\/Mimir, Honeycomb, Datadog, New Relic, or any OTEL-compatible destination).<\/p>\n
- \n
- GraphQL API, Functions, and BYOC services send traces, logs and metrics via OTLP\/HTTP(S).<\/li>\n
- An OpenTelemetry Collector receives, batches, samples, scrubs, and routes signals.<\/li>\n
- Dashboards and alerts run in your chosen tool, fed by the Collector\u2019s exporters.<\/li>\n<\/ul>\n
Signals and flow<\/h3>\n
Use W3C Trace Context so requests stitch across every hop. The traceparent<\/em> and tracestate<\/em> headers start in the GraphQL API, pass through Actions or Event Triggers to Serverless Functions, and return with enriched spans. Database timings appear in GraphQL resolver spans, so the same distributed trace shows client request, resolver latency, HTTP calls to Functions, and query timing inside Postgres.<\/p>\n
Required Nhost touchpoints<\/h3>\n
You do not need to provision or manage any Nhost servers. Configure environment variables in the Nhost Console for the GraphQL API and for Serverless Functions (Node\/TypeScript). Point them to your Collector\u2019s public OTLP endpoint, add a token header, and define resource attributes. Redeploy, and signals flow. That\u2019s it\u2014observability and monitoring without cluster setup.<\/p>\n
Prerequisites<\/h2>\n
- \n
- An OpenTelemetry Collector reachable over the internet (public URL) with a token or API key for auth.<\/li>\n
- Outbound HTTPS allowed from your Nhost project (default). Validate TLS and firewall rules on your Collector.<\/li>\n
- Your Nhost project subdomain\/ID (for resource attributes and filters).<\/li>\n
- Access to your telemetry backend (Grafana, Honeycomb, Datadog, etc.) to verify data and build dashboards.<\/li>\n<\/ul>\n
If you are still evaluating backend platforms and how they compare for tracing, auth, and pricing, see the open-source comparison: Nhost vs Supabase vs Appwrite (2026): Open-Source Backend Comparison for Postgres, GraphQL, Auth, and Pricing<\/a>.<\/p>\n
Enable OpenTelemetry in the GraphQL API<\/h2>\n
Turn on tracing and export to OTLP using environment variables in the Nhost Console. The GraphQL engine supports OpenTelemetry natively, so you do not add code or sidecars. After configuring, trigger a redeploy of the GraphQL service and confirm traces appear in your backend.<\/p>\n
Exporter endpoint and sampling<\/h3>\n
- \n
- Set your OTLP\/HTTP or OTLP\/gRPC endpoint to your Collector URL (HTTPS recommended).<\/li>\n
- Provide authentication via headers (for example, an Authorization<\/em> bearer token) in the exporter configuration.<\/li>\n
- Start with parent-based 10\u201320% sampling in the Collector or exporter. This balances visibility with cost and keeps performance monitoring representative. For incident triage, you can temporarily raise sampling to 100% to capture every trace.<\/li>\n<\/ul>\n
Resource attributes<\/h3>\n
- \n
- service.name<\/strong>: nhost-graphql<\/li>\n
- deployment.environment<\/strong>: dev, staging, or prod<\/li>\n
- nhost.project.id<\/strong>: your Nhost project ID or subdomain<\/li>\n
- Optional: service.version<\/strong> from Git SHA, and cloud.region<\/strong> if you run multi-region<\/li>\n<\/ul>\n
These attributes power clean service graphs and let you filter Nhost monitoring views by project and environment without cardinality explosions.<\/p>\n
Instrument Serverless Functions (Node\/TS)<\/h2>\n
For Functions, add the OpenTelemetry Node SDK once at startup and enable auto-instrumentation for HTTP servers, fetch\/axios, and popular libraries. Configure the SDK to export traces, logs and metrics to the same Collector as GraphQL. Because Functions run in a managed environment, set exporter details and resource attributes via Nhost environment variables, not hard-coded values.<\/p>\n
OTLP exporter config<\/h3>\n
- \n
- Use OTLP over HTTPS with a token in headers for secure delivery.<\/li>\n
- Mirror GraphQL settings for deployment.environment<\/em> and nhost.project.id<\/em> to keep dashboards and alerts unified.<\/li>\n
- Prefer batch exporters with reasonable flush intervals to minimize overhead.<\/li>\n<\/ul>\n
Context propagation<\/h3>\n
Forward and respect the traceparent<\/em> header. When GraphQL invokes Actions or Event Triggers, ensure the Function reads the trace context and continues the parent trace. When Functions call back into GraphQL or other services, include the same W3C headers so spans link bi-directionally. This is the key to end-to-end observability and monitoring that tells one story instead of scattering signals across isolated views.<\/p>\n
End-to-end trace: GraphQL -> Action -> Function -> Postgres<\/h2>\n
To validate setup, create a GraphQL Action that triggers a Function which queries Postgres through the GraphQL engine. In your trace, you should see:<\/p>\n
- \n
- The incoming GraphQL operation with operationName<\/em> and variables size<\/li>\n
- An HTTP client span from GraphQL to the Function (or an Action span if proxied)<\/li>\n
- Function spans for handler execution, external calls, and cache checks<\/li>\n
- Resolver\/database spans showing Postgres timings, row counts, and errors if any<\/li>\n<\/ul>\n
When that single trace shows the resolver and downstream Function time together, your performance monitoring workflow becomes straightforward: identify outliers, inspect spans, and pin down whether time is spent in validation, business logic, network, or the database.<\/p>\n
Database metrics and slow queries<\/h2>\n
You can extract a lot of value from GraphQL resolver spans. They include query timings and labels like operationName<\/em> and table\/field context. Use them to chart p95 latency by operation, error rate by mutation, and throughput across environments. This keeps Nhost monitoring focused on what users experience rather than raw query text.<\/p>\n
Optional postgres receiver<\/h3>\n
If you maintain a secure read-only connection outside of Nhost, add the Collector\u2019s Postgres receiver to scrape pg_stat*<\/em> views. Correlate with traces using db.system=postgres<\/em> and align service.name<\/em> and nhost.project.id<\/em>. Use this for capacity planning and query planning trends; keep high-cardinality fields like db.statement<\/em> sanitized or truncated to avoid metric blowups. If you prefer not to manage any DB connections, rely on resolver timings\u2014they are often sufficient for practical performance monitoring.<\/p>\n
Authentication and Storage signals<\/h2>\n
Instrument Auth webhooks and Storage handlers so they emit traces, logs and metrics. This lets you catch 401\/403 spikes, token issuance latency, and upload\/download slowdowns quickly. When a user flow fails, you want immediate visibility across signup, login, avatar upload, and profile update in a single distributed trace.<\/p>\n
For deeper guidance on securing agents and services with JWTs, see How to Add OAuth2 and JWT Authentication to Your AI Agents (Step-by-Step Guide)<\/a>. The same token practices apply to webhook auth and cross-service calls, and your logs and metrics should reflect token validation outcomes.<\/p>\n
Metrics to emit<\/h3>\n
- \n
- Auth<\/strong>: counters for signups, logins, refreshes; error counters by status (401, 403); latency histograms for token issuance and webhook processing<\/li>\n
- Storage<\/strong>: counters for uploads\/downloads; bytes_in\/bytes_out; latency histograms by object size bucket; error counters by status<\/li>\n
- Sessions<\/strong>: gauge for active sessions if available, counters for session starts\/ends<\/li>\n<\/ul>\n
Bring your own containers (polyglot services)<\/h2>\n
When you deploy BYOC services, run an OTEL Collector sidecar per service or embed language SDKs (Go, Python, Rust). Keep resource attributes aligned with Nhost components so dashboards remain cohesive:<\/p>\n
- \n
- service.name<\/strong>: meaningful and stable per service<\/li>\n
- nhost.project.id<\/strong>: same as GraphQL and Functions<\/li>\n
- deployment.environment<\/strong>: dev\/staging\/prod<\/li>\n<\/ul>\n
This standardization ensures Nhost monitoring spans all your services regardless of language or framework.<\/p>\n
Internal service calls<\/h3>\n
Ensure HTTP and gRPC clients propagate W3C headers. With consistent propagation between BYOC, Functions, and GraphQL, your traces remain contiguous\u2014even for multi-hop calls and retries. Add error attributes and retry metadata to spans so debugging intermittent failures doesn\u2019t require guessing.<\/p>\n
Logs and metrics that matter<\/h2>\n
Photo by Luke Chesser<\/a> on Unsplash<\/a><\/figcaption><\/figure>\n Emit structured JSON logs from Functions and BYOC services and route them through OTEL logs. Include trace_id<\/em> and span_id<\/em> in each log record. With this, a production error log jumps straight to the exact trace that captured the failure, eliminating context-switching. Your logs and metrics should tell the same story as your traces.<\/p>\n
Low-cardinality metrics<\/h3>\n
- \n
- request_duration<\/strong> (histogram) with labels: service.name, deployment.environment, operationName (for GraphQL)<\/li>\n
- error_rate<\/strong> (counter or ratio) with labels: service.name, status_class (2xx\/4xx\/5xx)<\/li>\n
- cold_start<\/strong> (counter) for Functions to track warmup impact<\/li>\n
- queue_time<\/strong> (histogram) when using queues; measure time-to-start vs time-in-handler<\/li>\n
- GraphQL resolver latency<\/strong> (histogram) by operationName and top-level field, not by full query text<\/li>\n<\/ul>\n
Favor stable labels and bucketing to avoid metric cardinality explosions. Your goal is actionable observability and monitoring, not an unbounded time series bill.<\/p>\n
Dashboards and alerts for Nhost stacks<\/h2>\n
Pre-build a few focused dashboards so engineers get answers in one view:<\/p>\n
- \n
- GraphQL<\/strong>: p95 latency by operationName; 5xx rate; top slow operations; request volume and cache hit\/miss if applicable<\/li>\n
- Functions<\/strong>: error budget burn; cold start counts and percent; handler p95; external call latency<\/li>\n
- Auth\/Storage<\/strong>: signup\/login success rate, token issuance latency, 401\/403 spikes; upload\/download p95 and egress volume<\/li>\n
- Postgres (optional)<\/strong>: lock wait time, buffer hit ratio, top tables by IO, correlated with resolver spans<\/li>\n<\/ul>\n
SLOs and alerts<\/h3>\n
- Functions<\/strong>: error budget burn; cold start counts and percent; handler p95; external call latency<\/li>\n
- error_rate<\/strong> (counter or ratio) with labels: service.name, status_class (2xx\/4xx\/5xx)<\/li>\n
- nhost.project.id<\/strong>: same as GraphQL and Functions<\/li>\n
- Storage<\/strong>: counters for uploads\/downloads; bytes_in\/bytes_out; latency histograms by object size bucket; error counters by status<\/li>\n
- Prefer batch exporters with reasonable flush intervals to minimize overhead.<\/li>\n<\/ul>\n
- deployment.environment<\/strong>: dev, staging, or prod<\/li>\n
- Start with parent-based 10\u201320% sampling in the Collector or exporter. This balances visibility with cost and keeps performance monitoring representative. For incident triage, you can temporarily raise sampling to 100% to capture every trace.<\/li>\n<\/ul>\n
![\"Speedcurve](\"https:\/\/images.unsplash.com\/photo-1551288049-bebda4e38f71?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixid=M3w4NDY5MTd8MHwxfHNlYXJjaHwxfHxvYnNlcnZhYmlsaXR5JTIwYW5kJTIwbW9uaXRvcmluZ3xlbnwwfDB8fHwxNzgzOTU2NzgwfDA&ixlib=rb-4.1.0&q=80&w=1080\")