[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["難以理解","hardToUnderstand","thumb-down"],["資訊或程式碼範例有誤","incorrectInformationOrSampleCode","thumb-down"],["缺少我需要的資訊/範例","missingTheInformationSamplesINeed","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間：2025-09-04 (世界標準時間)。"],[],[],null,["# Trace sampling\n\nThis document introduces the concept of *sampling* , which refers to whether\ndata for a [span](/trace/docs/traces-and-spans#span) is sent to Cloud Trace. When data for a span\nis sent to Cloud Trace, then that span is *sampled*. When data for every\nspan in a trace is recorded, the trace is complete. However, traces frequently\nhave missing spans because each instrumented component in a distributed tracing\nsystem independently decides whether or not to record the\nspan it is processing.\n\nAlthough each component makes its own decision as to whether the span it is\nprocessing is sampled, that decision can be influenced by the parent's\nsampling decision. For example, assume every component has a rule that says\n\"if the parent span is sampled, then sample the current span; otherwise,\nsample 50% of the spans\". In this scenario, the following is true:\n\n- The root span determines whether all spans in the trace are sampled.\n- When the root span is sampled, all spans in the trace are sampled. Therefore, the trace is complete.\n\nComponents can pass their sampling decision to the child by using context.\nFor example, in the World Wide Web Consortium (W3C)\n[`traceparent` header](https://www.w3.org/TR/trace-context/),\nthe [`sampled` flag](https://www.w3.org/TR/trace-context/#sampled-flag) stores the parent's sampling decision.\n\nDon't confuse sampling with [context propagation](/trace/docs/trace-context). Sampling\nrefers to whether a component records data about a span. Context propagation\nrefers to whether information about the span, such as the span ID, is\npassed to child components.\n\nSampling strategies\n-------------------\n\nSampling decisions can either be head-based or tail-based.\nIn *head-based sampling* , the sampling decision is made when the request is\nreceived by the component processing the span.\nIn *tail-based sampling*, the sampling decision is delayed\nuntil after the entire trace is available.\n\nYou might encounter the phrase \"100% sampling\" in documentation for\ndistributed tracing systems. This phrase might apply to a trace or to a\ncomponent. When applied to a trace, it means that all spans have been sampled,\nor equivalently, that the trace is complete. When applied to a component,\nit means that the component samples every span it processes.\n\n### Head-based sampling\n\nHead-based samplers are typically configured to always sample spans or to\nuse a probabilistic sampling strategy:\n\n- With *always sample* configurations, all components\n that service spans and that can write trace data, sample the spans they\n process. Ideally, all traces are complete,\n and therefore you have the information necessary to troubleshoot failures.\n This type of configuration might cause you to exceed [quotas](/trace/docs/quotas),\n or your storage cost limits.\n\n- With *probabilistic* sampling, not all spans are sampled.\n The actual behavior for this approach depends\n on the component's implementation. In some implementations, all spans have\n the same probability of being sampled. In others, the sampling decision of\n the parent influences whether a span is sampled.\n\nTraces might not contain every span. This might be expected due to the use of\n*probabilistic* sampling, or it might be due to quota, or to components that\nprocess a request but don't sample the span.\n\n### Tail-based sampling\n\nCloud Trace doesn't support tail-based sampling; sampling\ndecisions must be made in the components that send data to Cloud Trace.\n\nIf you want to use tail-based sampling, then you can use an intermediary\nserver that receives tracing information which relays data to\nCloud Trace after making a sampling decision. For example, you can use\nthe [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/)\nwith the [Tail Sampling Processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/tailsamplingprocessor)\nto make a delayed sampling decision.\n\nIf you plan to use tail sampling, consider the following:\n\n- You must store all spans in a trace before you make a sampling decision. Therefore, you might require a large amount of temporary storage or incur other overhead.\n- In general, all components that can generate spans for trace need to coordinate. Typically, developers that use OpenTelemetry route all spans for the same trace ID to the same collector.\n\nSampling and Google Cloud services\n----------------------------------\n\n| **Note:** Cloud Trace has no role in a component's sampling decision. Instead, Cloud Trace manages a repository for storing distributed tracing information.\n\nEach Google Cloud service makes its own sampling decisions,\nand not all Google Cloud services sample. That is, a service might never send\ndata to Cloud Trace.\n\nWhen sampling is supported by a Google Cloud service, that service typically\nimplements the following:\n\n- A default sample rate.\n- A mechanism to use the parent's sampling decision as a hint as to whether to sample the span.\n- Maximum sampling rate.\n\nTo request that a Google Cloud service add support for sampling,\nuse the [Google Issue Tracker](https://developers.google.com/issue-tracker/guides/access-ui).\n\nWhat's next\n-----------\n\n- For a discussion about how you can pick a sampling strategy by span name,\n see [Jaeger remote sampling](https://www.youtube.com/live/Q2K1rJn67X8?si=q6idOBJkaifykl9g&t=2574).\n\n- We recommend that you review the following open-source documentation to help\n you determine which sampling approach is best for your in-development and\n deployed applications:\n\n - [OpenTelemetry Sampling](https://opentelemetry.io/docs/concepts/sampling/)\n - [OpenTelemetry probability sampling](https://opentelemetry.io/docs/specs/otel/trace/tracestate-probability-sampling/)\n - [OpenTelemetry tail sampling processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/tailsamplingprocessor)\n - [`sampled` flag](https://www.w3.org/TR/trace-context/#sampled-flag)\n- Google Cloud service documentation:\n\n - [Enabling distributed tracing in Apigee](/apigee/docs/api-platform/develop/enabling-distributed-trace)\n - [Using distributed tracing with Cloud Run](/run/docs/trace)\n - [Cloud Endpoints: Trace sampling rate](/endpoints/docs/openapi/tracing#trace_sampling_rate)"]]
