grpc/grpc-go · error

failed to instrument OpenCensus

Error message

failed to instrument OpenCensus: %v

What it means

observability.Start called startOpenCensus and it failed; the wrapped %v is most often the Stackdriver exporter creation error (error 256) or the views registration error (error 257). The deferred End() runs to clean up partial state. Emitted at observability.go:72.

Solutions

1. Read the inner %v: if it is error 256, fix ADC / project / API enablement for Stackdriver; if error 257, deregister the duplicate views or stop the conflicting instrumentation.
2. Make sure your app does not also register opencensus.Default grpc views elsewhere — Start owns them when cloud_monitoring is on.
3. Call observability.Start exactly once per process.
4. If you don't need metrics/tracing, drop cloud_trace and cloud_monitoring from the config to skip OpenCensus setup entirely.

Example fix

// before
export GRPC_GCP_OBSERVABILITY_CONFIG='{"project_id":"","cloud_monitoring":{}}'

// after
export GRPC_GCP_OBSERVABILITY_CONFIG='{"project_id":"my-proj","cloud_monitoring":{}}'
export GOOGLE_APPLICATION_CREDENTIALS=/etc/sa.json

// Pre-flight: can we build the Stackdriver exporter and register views?
// Ensure default views are not already registered.
for _, v := range defaultViews {
    if vFor, err := view.Find(v.Name); err == nil && vFor != nil {
        return fmt.Errorf("view %s already registered; unregister before Start", v.Name)
    }
}

if err := observability.Start(ctx); err != nil {
    if strings.Contains(err.Error(), "failed to instrument OpenCensus") {
        // inner is 256 (exporter) or 257 (views); branch on substring
        return fmt.Errorf("OpenCensus instrumentation failed (ADC/API/duplicate views): %w", err)
    }
    return err
}

When it happens

Trigger: Config has cloud_trace and/or cloud_monitoring present, so startOpenCensus tries to build the Stackdriver exporter; that fails on bad ADC, bad project, disabled APIs, or the default views are already registered. Also when view.Register returns (error 257) because the views were registered by another package.

Common situations: App already calls opencensus view.Register for the same grpc views elsewhere; Stackdriver Monitoring/Trace API disabled; ADC missing; running Start twice in a test; conflicting OpenCensus instrumentation from another library.

Related errors

• failed to create Stackdriver exporter
• failed to register observability views
• failed to start logging
• no ObservabilityConfig found
• unable to create CloudLogging exporter

AI-assisted analysis of grpc/grpc-go@0c51461d27 (2026-08-11). Data as JSON: /api/errors/b8c114056a7e1aeb. Report an issue: GitHub.

Appendix: source

Thrown at gcp/observability/observability.go:72

		return fmt.Errorf("no ObservabilityConfig found")
	}

	// Set the project ID if it isn't configured manually.
	if err = ensureProjectIDInObservabilityConfig(ctx, config); err != nil {
		return err
	}

	// Cleanup any created resources this function created in case this function
	// errors.
	defer func() {
		if err != nil {
			End()
		}
	}()

	// Enabling tracing and metrics via OpenCensus
	if err = startOpenCensus(config); err != nil {
		return fmt.Errorf("failed to instrument OpenCensus: %v", err)
	}

	if err = startLogging(ctx, config); err != nil {
		return fmt.Errorf("failed to start logging: %v", err)
	}

	// Logging is controlled by the config at methods level.
	return nil
}

// End is the clean-up API for gRPC Observability plugin. It is expected to be
// invoked in the main function of the application. The suggested usage is
// "defer observability.End()". This function also flushes data to upstream, and
// cleanup resources.
//
// Note: this method should only be invoked once.
func End() {
	stopLogging()

View on GitHub (pinned to 0c51461d27)