grpc/grpc-go · error

error parsing observability config: invalid cloud trace…

Error message

error parsing observability config: invalid cloud trace sampling rate %v

What it means

cloud_trace.sampling_rate is a probability and must lie in [0.0, 1.0], but the parsed value was outside that range. Emitted at config.go:120 only when config.CloudTrace != nil, so omitting cloud_trace entirely avoids the check; a value of 0 is allowed (tracing disabled).

Solutions

1. Divide your percentage by 100: 5% becomes 0.05, 100% becomes 1.0.
2. If you want tracing off, either omit cloud_trace or set sampling_rate to 0.
3. Validate the value in your config pipeline with: if r<0||r>1 reject.
4. Restart the binary after fixing the config.

Example fix

// before
{"cloud_trace":{"sampling_rate":5}}

// after
{"cloud_trace":{"sampling_rate":0.05}}

if cfg.CloudTrace != nil && (cfg.CloudTrace.SamplingRate < 0 || cfg.CloudTrace.SamplingRate > 1) {
    return fmt.Errorf("sampling_rate %v out of [0,1]", cfg.CloudTrace.SamplingRate)
}

if err := observability.Start(ctx); err != nil {
    if strings.Contains(err.Error(), "invalid cloud trace sampling rate") {
        return fmt.Errorf("set cloud_trace.sampling_rate to a fraction in [0,1]: %w", err)
    }
    return err
}

When it happens

Trigger: Setting sampling_rate to a percentage like 5 (meaning 5%) instead of 0.05, to a negative number, or to a value > 1. Triggered when GRPC_GCP_OBSERVABILITY_CONFIG(_FILE) contains a cloud_trace block with such a value.

Common situations: Treating sampling_rate as a percent (0-100) instead of a fraction (0-1); typo adding a digit (1.5); templating mistake substituting an integer metric; misreading docs that say '5% chance' and writing 5.

Related errors

• cannot have a leading slash
• cannot have exclude and a '*' wildcard
• invalid method string
• method name must be non empty
• / must come in between service and method, only one /

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

Appendix: source

Thrown at gcp/observability/config.go:120

			return fmt.Errorf("error in serverRPCEvent method: %v", err)
		}
	}
	return nil
}

// unmarshalAndVerifyConfig unmarshals a json string representing an
// observability config into its internal go format, and also verifies the
// configuration's fields for validity.
func unmarshalAndVerifyConfig(rawJSON json.RawMessage) (*config, error) {
	var config config
	if err := json.Unmarshal(rawJSON, &config); err != nil {
		return nil, fmt.Errorf("error parsing observability config: %v", err)
	}
	if err := validateLoggingEvents(&config); err != nil {
		return nil, fmt.Errorf("error parsing observability config: %v", err)
	}
	if config.CloudTrace != nil && (config.CloudTrace.SamplingRate > 1 || config.CloudTrace.SamplingRate < 0) {
		return nil, fmt.Errorf("error parsing observability config: invalid cloud trace sampling rate %v", config.CloudTrace.SamplingRate)
	}
	logger.Infof("Parsed ObservabilityConfig: %+v", &config)
	return &config, nil
}

func parseObservabilityConfig() (*config, error) {
	if f := envconfig.ObservabilityConfigFile; f != "" {
		if envconfig.ObservabilityConfig != "" {
			logger.Warning("Ignoring GRPC_GCP_OBSERVABILITY_CONFIG and using GRPC_GCP_OBSERVABILITY_CONFIG_FILE contents.")
		}
		content, err := os.ReadFile(f)
		if err != nil {
			return nil, fmt.Errorf("error reading observability configuration file %q: %v", f, err)
		}
		return unmarshalAndVerifyConfig(content)
	} else if envconfig.ObservabilityConfig != "" {
		return unmarshalAndVerifyConfig([]byte(envconfig.ObservabilityConfig))
	}

View on GitHub (pinned to 0c51461d27)