In Trace, How to see the value of a private variable?  

Apigee has a really handy feature, the Trace Session.

This is exposed to the user via the Trace UI. Within the Trace UI, an operator can examine each request handled by an API Proxy:

• the inbound request, including verb, path, payload, headers
• the effects of each policy in an API Proxy, including context variables set and read
• the time taken for each policy to execute
• the request (verb, path, payload, headers) sent to the backend
• the response (status, payload, headers) received from the backend
• the response (status, payload, headers) sent to the original client

The Trace feature (the runtime trace session capability as well as the Trace UI) is very useful when developing API Proxies, and can also be useful when diagnosing problems with APIs that are actually in production. Imagine being able to see every Read and Write of a context variable! It's very detailed.

For example, when the policy is VerifyAccessToken, the trace session will show the token that is being validated, the API Product that the token is good for, the expiry of the token, the scope, and any custom attributes attached to the token, or the product, or the developer, or the app. When the policy is a KVM Get, the trace session will show the value read from the KVM. And so on. With Trace, you can evaluate and see the effects of each discrete policy.

The Trace session is designed to handle enterprise requirements. For example, some data by Apigee API Proxies is private; maybe it is Personally Identifiable Information (PII), maybe it is private health information, maybe it is a private key used for signatures, and that key must not be disclosed.

To comply with enterprise requirements for privacy in these kinds of cases, Trace supports data masking. This means for some variables, Trace will NOT display the values read or written. Instead it will show masked values, like "*****". This prevents disclosure of PII or other private information.

The Trace session evaluates which variables should be shown in cleartext, and which should be masked, via the maskconfig object. Each Apigee customer can set maskconfigs, either on an organization or an an API Proxy scope, or both. This tells Trace the names of the variables that must be masked. One of the "variable name patterns" that Trace always masks is "private.ANYTHING". If the variable name begins with "private.", then it will not appear in a Trace session. As a complement, if you have a KVM Get policy, and you're using an encrypted KVM, then you MUST read the value into a variable that uses that "private." prefix. This means Trace will never show the value read from an encrypted KVM.

Ok that's great for enterprise security compliance, but suppose you are still in the development phase, the data is test data, not actually PII, and you want to use Trace to see what has been read from an Encrypted KVM. Is it possible?

Not directly, but with this "one weird trick" you can sidestep the masking: Insert an AssignMessage policy immediately AFTER the policy that sets a private variable, such as a KVM Get that accesses an encrypted KVM. It looks like this:

<AssignMessage name='AM-Diagnostics'>
  <AssignVariable>
    <Name>diags.my_private_variable</Name> <!-- this name can be anything -->
    <Ref>private.my_private_variable</Ref> <!-- the name of the private var you want to see -->
  </AssignVariable>
  ... 
<!-- more AssignVariable entries here if needed . -->
<!-- use distinct Name values, else Trace UI may not display each assignment.  -->
  ...
</AssignMessage>

If you use that approach, then the Trace session will show a Set entry on "diags.my_private_variable".

BTW that might be a thing to check for in your bundle linter step. Check for the use of private variables in an AssignVariable/Ref element, which as I said would sidestep the intended privacy protections. Not foolproof but maybe it would catch some cases.

You can use the same approach to check the values of any other variables that have been masked with maskconfigs.

I hope this tip is helpful!

Let me know if questions.