{"record":{"id":"6b5619cc11b93161","repo":"grpc/grpc-go","slug":"error-parsing-observability-config-invalid-cloud","errorCode":null,"errorMessage":"error parsing observability config: invalid cloud trace sampling rate %v","messagePattern":"error parsing observability config: invalid cloud trace sampling rate (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"gcp/observability/config.go","lineNumber":120,"sourceCode":"\t\t\treturn fmt.Errorf(\"error in serverRPCEvent method: %v\", err)\n\t\t}\n\t}\n\treturn nil\n}\n\n// unmarshalAndVerifyConfig unmarshals a json string representing an\n// observability config into its internal go format, and also verifies the\n// configuration's fields for validity.\nfunc unmarshalAndVerifyConfig(rawJSON json.RawMessage) (*config, error) {\n\tvar config config\n\tif err := json.Unmarshal(rawJSON, &config); err != nil {\n\t\treturn nil, fmt.Errorf(\"error parsing observability config: %v\", err)\n\t}\n\tif err := validateLoggingEvents(&config); err != nil {\n\t\treturn nil, fmt.Errorf(\"error parsing observability config: %v\", err)\n\t}\n\tif config.CloudTrace != nil && (config.CloudTrace.SamplingRate > 1 || config.CloudTrace.SamplingRate < 0) {\n\t\treturn nil, fmt.Errorf(\"error parsing observability config: invalid cloud trace sampling rate %v\", config.CloudTrace.SamplingRate)\n\t}\n\tlogger.Infof(\"Parsed ObservabilityConfig: %+v\", &config)\n\treturn &config, nil\n}\n\nfunc parseObservabilityConfig() (*config, error) {\n\tif f := envconfig.ObservabilityConfigFile; f != \"\" {\n\t\tif envconfig.ObservabilityConfig != \"\" {\n\t\t\tlogger.Warning(\"Ignoring GRPC_GCP_OBSERVABILITY_CONFIG and using GRPC_GCP_OBSERVABILITY_CONFIG_FILE contents.\")\n\t\t}\n\t\tcontent, err := os.ReadFile(f)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"error reading observability configuration file %q: %v\", f, err)\n\t\t}\n\t\treturn unmarshalAndVerifyConfig(content)\n\t} else if envconfig.ObservabilityConfig != \"\" {\n\t\treturn unmarshalAndVerifyConfig([]byte(envconfig.ObservabilityConfig))\n\t}","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/grpc/grpc-go/blob/0c51461d27177d997e14c642fe18c11668fc09a3/gcp/observability/config.go#L102-L138","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Divide your percentage by 100: 5% becomes 0.05, 100% becomes 1.0.","If you want tracing off, either omit cloud_trace or set sampling_rate to 0.","Validate the value in your config pipeline with: if r<0||r>1 reject.","Restart the binary after fixing the config."],"exampleFix":"// before\n{\"cloud_trace\":{\"sampling_rate\":5}}\n\n// after\n{\"cloud_trace\":{\"sampling_rate\":0.05}}","handlingStrategy":"validation","validationCode":"if cfg.CloudTrace != nil && (cfg.CloudTrace.SamplingRate < 0 || cfg.CloudTrace.SamplingRate > 1) {\n    return fmt.Errorf(\"sampling_rate %v out of [0,1]\", cfg.CloudTrace.SamplingRate)\n}","typeGuard":null,"tryCatchPattern":"if err := observability.Start(ctx); err != nil {\n    if strings.Contains(err.Error(), \"invalid cloud trace sampling rate\") {\n        return fmt.Errorf(\"set cloud_trace.sampling_rate to a fraction in [0,1]: %w\", err)\n    }\n    return err\n}","preventionTips":["Treat sampling_rate as a fraction, not a percent.","Add a JSON schema constraint: {\"minimum\":0,\"maximum\":1}.","Document the range next to the field in your config template."],"tags":["observability","config","cloud-trace","validation"],"backgroundTag":null,"analyzedSha":"0c51461d27177d997e14c642fe18c11668fc09a3","analyzedAt":"2026-08-11T14:49:15.055Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}