[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["很难理解","hardToUnderstand","thumb-down"],["信息或示例代码不正确","incorrectInformationOrSampleCode","thumb-down"],["没有我需要的信息/示例","missingTheInformationSamplesINeed","thumb-down"],["翻译问题","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC)：2025-09-04。"],[[["\u003cp\u003eThe TraceCapture policy in Apigee allows you to add custom variables to the runtime's trace data beyond the default set, enhancing your ability to monitor specific flow, policy, or custom variables.\u003c/p\u003e\n"],["\u003cp\u003eThis policy is an Extensible policy, which may have cost or utilization implications depending on your Apigee license, as outlined in the Policy types documentation.\u003c/p\u003e\n"],["\u003cp\u003eThe TraceCapture policy is configured using the \u003ccode\u003e<TraceCapture>\u003c/code\u003e element, which defines the policy's behavior, including display name, variables to trace, handling of unresolved variables, and limits on variable size.\u003c/p\u003e\n"],["\u003cp\u003eYou can add additional variables to the distributed tracing reports by using the \u003ccode\u003e<Variables>\u003c/code\u003e and \u003ccode\u003e<Variable>\u003c/code\u003e child elements, but it's important to note that tracing \u003ccode\u003eprivate\u003c/code\u003e and \u003ccode\u003epolicy.secret\u003c/code\u003e variables are not allowed.\u003c/p\u003e\n"],["\u003cp\u003eThe policy can throw errors if variables are out of scope or cannot be resolved, or if a variable exceeds 256 bytes and \u003ccode\u003e<ThrowExceptionOnLimit>\u003c/code\u003e is set to \u003ccode\u003etrue\u003c/code\u003e, as indicated by the \u003ccode\u003esteps.tracecapture.UnresolvedVariable\u003c/code\u003e and \u003ccode\u003esteps.tracecapture.VariableValueLimitExceeded\u003c/code\u003e fault codes.\u003c/p\u003e\n"]]],[],null,["# TraceCapture policy\n\n*This page\napplies to **Apigee** and **Apigee hybrid**.*\n\n\n*View [Apigee Edge](https://docs.apigee.com/api-platform/get-started/what-apigee-edge) documentation.*\n\n|\n| **Preview**\n|\n|\n| This product or feature is subject to the \"Pre-GA Offerings Terms\" in the General Service Terms section\n| of the [Service Specific Terms](/terms/service-terms#1).\n|\n| Pre-GA products and features are available \"as is\" and might have limited support.\n|\n| For more information, see the\n| [launch stage descriptions](/products#product-launch-stages).\n\nOverview\n--------\n\nThe TraceCapture policy lets you add additional variables to your Apigee runtime's\ntrace data. If you have enabled distributed tracing for the Apigee runtime,\nthe runtime, by default, traces a set of pre-defined variables. For more information, see\n[Default trace variables in tracing report](/apigee/docs/api-platform/develop/enabling-distributed-trace#default-trace-var).\nHowever, if you want the Apigee runtime to trace additional flow, policy, or custom variables, use the TraceCapture\npolicy. You can use this policy either in the request or the response flow. In your distributed\ntracing report, you can view the variables added by TraceCapture policy\nin the `TraceCaptureExecution` span.\n\nThis policy is an *Extensible policy* and use of this policy might have cost or\nutilization implications, depending on your Apigee license. For information on policy types\nand usage implications, see\n[Policy types](/apigee/docs/api-platform/reference/policies/reference-overview-policy#policy-types).\n\n`\u003cTraceCapture\u003e`\n----------------\n\nDefines the TraceCapture policy.\n\nThe `\u003cTraceCapture\u003e` element uses the following syntax: \n\n### Syntax\n\n```scdoc\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cTraceCapture continueOnError=\"true\" enabled=\"true\" name=\"DistributedTraceCapture-1\"\u003e\n \u003cDisplayName\u003ePOLICY_DISPLAY_NAME\u003c/DisplayName\u003e\n \u003cVariables\u003e\n \u003cVariable name=\"TRACE_VARIABLE_NAME\" ref=\"FLOW_VARIABLE_NAME\"\u003eDEFAULT_VALUE\u003c/Variable\u003e\n \u003cVariable name=\"TRACE_VARIABLE_NAME\" ref=\"FLOW_VARIABLE_NAME\"\u003eDEFAULT_VALUE\u003c/Variable\u003e\n \u003c/Variables\u003e\n \u003cIgnoreUnresolvedVariables\u003eBOOLEAN_VALUE\u003c/IgnoreUnresolvedVariables\u003e\n \u003cThrowExceptionOnLimit\u003eBOOLEAN_VALUE\u003c/ThrowExceptionOnLimit\u003e\n\u003c/TraceCapture\u003e\n```\n\n### Example\n\nThe following example shows the TraceCapture policy definition: \n\n```gdscript\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cTraceCapture continueOnError=\"true\" enabled=\"true\" name=\"DistributedTraceCapture-1\"\u003e\n \u003cDisplayName\u003eDistributed-Trace-Capture-Policy-1\u003c/DisplayName\u003e\n \u003cVariables\u003e\n \u003cVariable name=\"trace-variable-1\" ref=\"flow-variable-1\"\u003edefault-val-1\u003c/Variable\u003e\n \u003cVariable name=\"trace-variable-2\" ref=\"flow-variable-2\"\u003edefault-val-2\u003c/Variable\u003e\n \u003c/Variables\u003e\n \u003cIgnoreUnresolvedVariables\u003efalse\u003c/IgnoreUnresolvedVariables\u003e\n \u003cThrowExceptionOnLimit\u003efalse\u003c/ThrowExceptionOnLimit\u003e\n\u003c/TraceCapture\u003e\n```\n\nThis element has the following attributes that are common to all policies:\n\nThe following table provides a high-level description of the child elements of [`\u003cTraceCapture\u003e`](/apigee/docs/api-platform/reference/policies/trace-capture-policy#tracecapture):\n\nChild element reference\n-----------------------\n\nThis section describes the child elements of [`\u003cTraceCapture\u003e`](/apigee/docs/api-platform/reference/policies/trace-capture-policy#tracecapture).\n\n### `\u003cDisplayName\u003e`\n\nUse in addition to the `name` attribute to label the policy in the\nmanagement UI proxy editor with a different, more natural-sounding name.\n\nThe `\u003cDisplayName\u003e` element is common to all policies.\n\nThe `\u003cDisplayName\u003e` element uses the following syntax: \n\n### Syntax\n\n```scdoc\n\u003cPolicyElement\u003e\n \u003cDisplayName\u003e\u003cvar translate=\"no\"\u003ePOLICY_DISPLAY_NAME\u003c/var\u003e\u003c/DisplayName\u003e\n ...\n\u003c/PolicyElement\u003e\n```\n\n### Example\n\n```text\n\u003cPolicyElement\u003e\n \u003cDisplayName\u003eMy Validation Policy\u003c/DisplayName\u003e\n\u003c/PolicyElement\u003e\n```\n\nThe `\u003cDisplayName\u003e` element has no attributes or child elements.\n\n### `\u003cVariables\u003e`\n\nSpecifies the list of variables to trace.\n\nThe `\u003cVariables\u003e` element uses the following syntax: \n\n#### Syntax\n\n```scdoc\n\u003cVariables\u003e\n \u003cVariable name=\"TRACE_VARIABLE_NAME\" ref=\"FLOW_VARIABLE_NAME\"\u003eDEFAULT_VALUE\u003c/Variable\u003e\n \u003cVariable name=\"TRACE_VARIABLE_NAME\" ref=\"FLOW_VARIABLE_NAME\"\u003eDEFAULT_VALUE\u003c/Variable\u003e\n\u003c/Variables\u003e\n```\n\n#### Example\n\nThe following example traces the `flow-variable-1` and `flow-variable-2` flow variables: \n\n```gdscript\n\u003cVariables\u003e\n \u003cVariable name=\"trace-variable-1\" ref=\"flow-variable-1\"\u003edefault-val-1\u003c/Variable\u003e\n \u003cVariable name=\"trace-variable-2\" ref=\"flow-variable-2\"\u003edefault-val-2\u003c/Variable\u003e\n\u003c/Variables\u003e\n```\n| **Note** :\n|\n| - You cannot trace `private` and `policy.secret` variables.\n| - Apigee recommends you to configure a maximum of `15` variables for Cloud Trace and a maximum of `25` variables for Jaeger.\n\n#### `\u003cVariable\u003e`\n\nSpecifies the variables to be added in the trace data.\n\nThe `\u003cVariable\u003e` element uses the following syntax: \n\n##### Syntax\n\n```scdoc\n\u003cVariable name=\"TRACE_VARIABLE_NAME\" ref=\"FLOW_VARIABLE_NAME\"\u003eDEFAULT_VALUE\u003c/Variable\u003e\n```\n\n##### Example\n\nThe following example sets the `trace-variable-1` trace variable to the\nvalue of the `flow-variable-1` flow variable: \n\n```gdscript\n\u003cVariable name=\"trace-variable-1\" ref=\"flow-variable-1\"\u003edefault-val-1\u003c/Variable\u003e\n```\n\nIf the `flow-variable-1` flow variable is not available,\n`trace-variable-1` is set to the default value `default-val-1`.\n\nThe following table describes the attributes of `\u003cVariable\u003e`:\n\n| **Note** : You can specify an optional default value for a variable. If the variable specified in `ref` is undefined in a request or a response, the trace data will have the default value for the variable.\n\n### `\u003cIgnoreUnresolvedVariables\u003e`\n\nDetermines whether processing stops when an unresolved variable is encountered.\n\nSet to `true` to ignore unresolved variables and continue processing; otherwise `false`. The\ndefault value is `true`.\n\nSetting `\u003cIgnoreUnresolvedVariables\u003e` to `true` is different from setting the [`\u003cTraceCapture\u003e`](/apigee/docs/api-platform/reference/policies/trace-capture-policy#tracecapture)'s\n`continueOnError` to `true`. If you set `continueOnError` to `true`, Apigee ignores all errors, not\nonly errors in variables.\n\nThe `\u003cIgnoreUnresolvedVariables\u003e` element uses the following syntax: \n\n### Syntax\n\n```scdoc\n\u003cIgnoreUnresolvedVariables\u003eBOOLEAN_VALUE\u003c/IgnoreUnresolvedVariables\u003e\n```\n\n### Example\n\nThe following example sets `\u003cIgnoreUnresolvedVariables\u003e` to `false`: \n\n```text\n\u003cIgnoreUnresolvedVariables\u003efalse\u003c/IgnoreUnresolvedVariables\u003e\n```\n| **Note** : The default value of the element is `false`.\n\n### `\u003cThrowExceptionOnLimit\u003e`\n\nSpecifies the behavior of the policy when the size of the variable exceeds the limit of\n256 bytes.\n\n- If set to `true`, the policy throws an error if a variable size exceeds the limit.\n- If set to `false`, the policy truncates the variable that exceeds the limit. The variable is truncated to the size of the limit.\n\n| **Note** : The default value of the element is `false`.\n\nThe `\u003cThrowExceptionOnLimit\u003e` element uses the following syntax: \n\n#### Syntax\n\n```scdoc\n\u003cThrowExceptionOnLimit\u003eBOOLEAN_VALUE\u003c/ThrowExceptionOnLimit\u003e\n```\n\n#### Example\n\nThe following example sets the `\u003cThrowExceptionOnLimit\u003e` value to `true`. \n\n```text\n\u003cThrowExceptionOnLimit\u003efalse\u003c/ThrowExceptionOnLimit\u003e\n```\n\nError codes\n-----------\n\nThis section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error.\nThis information is important to know if you are developing fault rules to\nhandle faults. To learn more, see [What you need to know\nabout policy errors](/apigee/docs/api-platform/fundamentals/what-you-need-know-about-policy-errors) and [Handling\nfaults](/apigee/docs/api-platform/fundamentals/fault-handling).\n\n### Runtime errors\n\nThese errors can occur when the policy executes.\n\n### Fault variables\n\nWhenever there are execution errors in a policy, Apigee generates error messages. You can view\nthese error messages in the error response. Many a time, system generated error messages might not be relevant\nin the context of your product. You might want to customize the error messages based on the\ntype of error to make the messages more meaningful.\n\nTo customize the error messages, you can use either fault rules or the RaiseFault policy. For\ninformation about differences between fault rules and the RaiseFault policy, see\n[FaultRules vs. the RaiseFault policy](/apigee/docs/api-platform/fundamentals/fault-handling#rulesvraisefault).\nYou must check for conditions using the `Condition` element in both the fault rules and the RaiseFault policy.\nApigee provides fault variables unique to each policy and the values of the fault variables are set when a policy triggers runtime errors.\nBy using these variables, you can check for specific error conditions and take appropriate actions. For more information about checking error\nconditions, see [Building conditions](/apigee/docs/api-platform/fundamentals/fault-handling#buildingconditions).\n\nThe following table describes the fault variables specific to this policy.\n\nFor more information about policy errors, see [What you\nneed to know about policy errors](/apigee/docs/api-platform/fundamentals/what-you-need-know-about-policy-errors)."]]
