AppGate telemetry spans

Prev Next

The following tables list span names and their descriptions:

Controller spans

Span

Description

appgate.controller.audit.post

Writes the audit event log and records the entitled Site IDs.

appgate.controller.auto_update_criteria.evaluate

Evaluates the client auto-update criteria script.

appgate.controller.cert.persist

Revokes the previous certificate for the subject and inserts the newly issued certificate.

appgate.controller.cert.public_key_parse

Parses the RSA public key from the certificate signing request (CSR) body that the client sends.

appgate.controller.cert.sign

Signs the client certificate with the private key of the certificate authority (CA).

appgate.controller.cert.validity_window

Calculates the notBefore and notAfter validity window for a client certificate.

appgate.controller.claims_token.build

Builds and populates the claims token.

{http.request.method} {http.route}

Handles a client representational state transfer (REST) request on the sign-in, authorization, or certificate signing path. The span name is the HTTP method and route of the request.

appgate.controller.client_update_url.await

Waits for the client auto-update URL, which another thread resolves.

appgate.controller.device.onboard

Registers a client device that the Controller doesn't already know.

appgate.controller.idp.authenticate

Completes the round trip to the identity provider (IdP), such as Lightweight Directory Access Protocol (LDAP), Remote Authentication Dial-In User Service (RADIUS), Security Assertion Markup Language (SAML), or OpenID Connect (OIDC).

appgate.controller.ip.allocate

Allocates a tunnel IP address from the IP pool.

appgate.controller.license.check

Checks the user license.

appgate.controller.otp.initialize

Issues a one-time password (OTP) challenge.

appgate.controller.otp.validate

Validates an OTP answer.

appgate.controller.policy.analyze

Matches policies and resolves entitlements to reach the policy decision.

appgate.controller.policy.evaluate_all

Evaluates all policies for the user across several threads within the remaining time budget.

appgate.controller.rate_limit.acquire

Waits for an available slot from the authorization rate limiter.

appgate.controller.risk.evaluate

Calls the risk service.

appgate.controller.system_claims.resolve

Resolves system claims, including the GeoIP lookup.

appgate.controller.token.sign

Signs a claims token or entitlement token.

appgate.controller.user_scripts.run

Evaluates user claim scripts.

Gateway spans

Span

Description

appgate.gateway.acl.convert_action

Converts a single entitlement IP access action into an access control list (ACL) rule set.

appgate.gateway.acl.generation

Generates the complete ACL rule set for a session from all entitled actions.

appgate.gateway.acl.send

Sends the ACL rule set to vpnd over the Gateway interprocess communication (IPC) socket.

appgate.gateway.arp.garp_burst

Sends a gratuitous Address Resolution Protocol (ARP) burst to announce that the Gateway now owns an IPv4 client tunnel IP address.

appgate.gateway.client_certificate.dn_extract

Extracts the distinguished name (DN) from the client certificate that the client presents during the tunnel handshake.

appgate.gateway.client_certificate.verify

Verifies the client certificate chain that the client presents during the tunnel handshake.

appgate.gateway.connection.registration

Registers an established client tunnel with the session daemon over the Gateway IPC socket.

appgate.gateway.connector_subnet.expand

Expands every Connector subnet in a proxy IP message to host IP addresses.

appgate.gateway.dns.udp.handler

Handles a Domain Name System (DNS) User Datagram Protocol (UDP) request in gonamed. For query requests, this span wraps DNS name extraction, the nested DNS name resolution chain, and response writing. For notify requests, this span records the handler outcome and doesn't create nested name resolution spans.

appgate.gateway.failover.advertisement

Advertises to the session manager that the Gateway released a client tunnel IP address.

appgate.gateway.failover.relinquish

Releases ownership of a client tunnel IP address after a peer Gateway announces it, and notifies the session manager.

appgate.gateway.guacd.access.decision

Evaluates the entitlement ACL for a brokered session request, including any name resolution that the request requires.

appgate.gateway.guacd.acl.apply

Applies an ACL push for one client tunnel IP address on the broker.

appgate.gateway.guacd.backend.dial

Opens a Transmission Control Protocol (TCP) connection to the local guacd instance for the target protocol.

appgate.gateway.guacd.backend.handshake

Performs the Guacamole handshake with the local guacd instance, from protocol selection to the ready instruction that contains the connection ID.

appgate.gateway.guacd.brokered_hosts.send

Sends the session manager the addresses that the broker resolved for a brokered host.

appgate.gateway.guacd.credentials.apply

Applies an administrator-injected credential push for one client tunnel IP address on the broker.

appgate.gateway.guacd.ipc.register

Registers the broker with the session manager when the broker connects.

appgate.gateway.guacd.observe.start

Starts a read-only observer session when an administrator joins a live brokered session.

appgate.gateway.guacd.recording.preflight

Confirms that the session recording exists and that its manifest is written before the client connection is upgraded.

appgate.gateway.guacd.session.establish

Redeems a tunnel token for a live brokered session, from token validation to the WebSocket upgrade.

appgate.gateway.guacd.session.list

Handles a request for the registry of live brokered sessions on the broker.

appgate.gateway.guacd.session.terminate

Handles an administrator request to terminate a live brokered session on the broker.

appgate.gateway.guacd.token.issue

Issues a single-use tunnel token that authorizes one brokered Secure Shell (SSH) or Remote Desktop Protocol (RDP) session.

appgate.gateway.guacd.token.validate

Validates and consumes a single-use tunnel token.

appgate.gateway.guacd.websocket.upgrade

Performs the WebSocket upgrade that hands the established session to the client.

appgate.gateway.guacproxy.acl.send

Sends the broker the brokered remote session ACL rules that apply to one client tunnel IP address.

appgate.gateway.guacproxy.brokered_hosts

Processes the addresses that the broker resolved for a brokered host in the session manager.

appgate.gateway.guacproxy.credentials.send

Sends the broker the administrator-injected secrets for one client tunnel IP address.

appgate.gateway.guacproxy.register

Processes the broker registration in the session manager and triggers a full resync of the ACLs and injected credentials for every live session.

appgate.gateway.guacproxy.request

Sends a request to the broker to list or terminate live brokered sessions for an administrator, and receives the response.

appgate.gateway.ha.advertisement

Processes an advertisement from the high availability (HA) daemon in the session manager when a peer Gateway takes over a client tunnel IP address.

appgate.gateway.ha.proxy_ips.send

Sends an add-proxy-ips or remove-proxy-ips notification that tells the HA daemon which client tunnel IP addresses the Gateway proxies for.

appgate.gateway.ha.register

Processes the HA daemon registration in the session manager and triggers a full resync of every live client tunnel IP address to the daemon.

{rpc.method}

Handles an inbound JSON remote procedure call (JSON-RPC) request from vpnd for a client command, such as login, update-tokens, or reconnect. The span name is the name of the RPC method.

appgate.gateway.ipc.register

Registers the HA daemon with the session manager once per connection.

appgate.gateway.login

Records the internal Gateway login operation.

appgate.gateway.nameresolve.dns.cache_lookup

Checks the cache for a single DNS-type name before any provider fanout. The Gateway creates one child span for each name under appgate.gateway.nameresolve.dns.resolve.

appgate.gateway.nameresolve.dns.list

Lists resources that match a single DNS-type name query for the ListResourcesNames RPC, which the list resources command uses. This span is separate from appgate.gateway.nameresolve.resolve and doesn't use the cache.

appgate.gateway.nameresolve.dns.list_provider

Calls a single configured DNS resolver to list resources for the name from appgate.gateway.nameresolve.dns.list. The Gateway creates one span for each configured DNS resolver, and the spans run in parallel.

appgate.gateway.nameresolve.dns.lookup

Sends a DNS query for a single record type, such as A or AAAA. The Gateway creates one span for each record type and emits this span only under appgate.gateway.nameresolve.dns.provider_fanout. The resource name path doesn't use this span.

appgate.gateway.nameresolve.dns.provider_fanout

Dispatches a DNS-type name to the DNS resolver after a cache miss. For other provider types, see appgate.gateway.nameresolve.resource_name.provider_fanout.

appgate.gateway.nameresolve.dns.resolve

Fans out over all DNS-type names in a resolve-names request. The Gateway creates one span for each request that contains one or more DNS-type names, and one appgate.gateway.nameresolve.dns.cache_lookup child span for each DNS-type name. If the request also contains resource-name-type names, a sibling appgate.gateway.nameresolve.resource_name.resolve span exists. The appgate.gateway.nameresolve.names.count attribute on this span reports the number of DNS-type names, not the total number of names in the request.

appgate.gateway.nameresolve.resolve

Resolves a batch of one or more names for a caller, such as sessiond or vpnd. This span is the RPC entry point, and the Gateway creates one span for each resolve-names request. A request can contain both DNS-type and resource-name-type names, and each type has its own child span.

appgate.gateway.nameresolve.resource_name.aws.lookup

Sends an Amazon Web Services (AWS) API lookup for a resource name entry.

appgate.gateway.nameresolve.resource_name.cache_lookup

Checks the cache for a single resource-name-type name before any provider fanout. The Gateway creates one child span for each name under appgate.gateway.nameresolve.resource_name.resolve.

appgate.gateway.nameresolve.resource_name.list

Lists resources that match a single resource-name-type name query for the ListResourcesNames RPC, which the list resources command uses. This span is separate from appgate.gateway.nameresolve.resolve and doesn't use the cache.

appgate.gateway.nameresolve.resource_name.list_provider

Calls a single configured resolver of the provider type to list resources for the name from appgate.gateway.nameresolve.resource_name.list. The Gateway creates one span for each configured resolver of that type, and the spans run in parallel.

appgate.gateway.nameresolve.resource_name.provider_fanout

Dispatches a resource-name-type name to the resolvers for its configured provider type after a cache miss. For AWS-type names, this span emits appgate.gateway.nameresolve.resource_name.aws.lookup. Each resolver dispatches only within its own provider type and doesn't fall back to other providers.

appgate.gateway.nameresolve.resource_name.resolve

Fans out over all resource-name-type names, such as AWS tag queries, in a resolve-names request. The Gateway creates one span for each request that contains one or more resource-name-type names, and one appgate.gateway.nameresolve.resource_name.cache_lookup child span for each resource-name-type name. If the request also contains DNS-type names, a sibling appgate.gateway.nameresolve.dns.resolve span exists. The appgate.gateway.nameresolve.names.count attribute on this span reports the number of resource-name-type names, not the total number of names in the request.

appgate.gateway.nd.unsolicited_na_burst

Sends an unsolicited Neighbor Advertisement burst to announce that the Gateway now owns an IPv6 client tunnel IP address.

appgate.gateway.policy.condition.evaluate

Evaluates a single policy condition script. The script runs on a virtual-thread executor, and the Gateway captures the parent context at submission time.

appgate.gateway.policy.condition.result

Records the outcome of a single policy condition evaluation.

appgate.gateway.policy.evaluation

Runs the full policy evaluation cycle for a session, from condition evaluation through ACL generation and the push to vpnd.

appgate.gateway.proxy_ip.add

Handles an inbound add-proxy-ips request. The Gateway takes ownership of the listed client tunnel IP addresses and announces them on the network.

appgate.gateway.proxy_ip.fanout

Dispatches the non-Connector client tunnel IP addresses in a proxy IP message to the goroutines that own the proxy maps.

appgate.gateway.proxy_ip.remove

Handles an inbound remove-proxy-ips request. The Gateway releases ownership of the listed client tunnel IP addresses.

appgate.gateway.proxyd.hole_punch

Performs UDP hole punching on the Gateway for one notify-gw message. This span continues the broker Signal session trace through the traceparent in the notify-gw metadata.

appgate.gateway.proxyd.relay_setup

Sets up a relay on the Gateway for one notify-gw-relay message. This span continues the broker Signal session trace through the traceparent in the notify-gw-relay metadata.

appgate.gateway.proxyd.signal.session

Represents a user Signal channel on the Connection Broker. This span is the root of the trace for a brokered connection. It continues a client-supplied traceparent from the Signal version request, if one exists, or starts a new trace.

appgate.gateway.proxyd.spa.accept

Authorizes a directly accepted connection with single packet authorization (SPA) and hands off its file descriptor. This span is the trace root for the direct path, which has no broker leg, and passes its traceparent to cz-vpnd during the handoff.

appgate.gateway.token.expiry_check

Checks whether a JSON Web Token (JWT) claims token or entitlement token is expired.

appgate.gateway.token.matching

Verifies that a claims token and an entitlement token belong together by matching the Site ID, DN, and claims token ID.

appgate.gateway.token.revocation_check

Checks whether a claims token or entitlement token is on the Controller revocation list.

appgate.gateway.token.signature_verification

Verifies the cryptographic signature of a JWT claims token or entitlement token against the Controller root certificate authority (CA).

appgate.gateway.tunnel.handshake

Establishes a client virtual private network (VPN) tunnel in cz-vpnd, from accepting the handed-over socket to registering the connection with the session daemon.

Sign-in and sign-out spans

The following table lists the spans for the sign-in and sign-out flows:

Span

Description

appgate.signin

Represents the root span for an AppGate sign-in flow. The client creates this span, which wraps the sign-in and Gateway Connect operations.

appgate.signin.authentication

Verifies the primary credentials of the user during sign-in.

appgate.signin.authorize

Determines the entitlements that the authenticated user receives during sign-in.

appgate.signin.controller

Wraps the calls from the client to the Controller during sign-in. The client creates this span.

appgate.signin.external_provider.token_exchange

Sends a token exchange request to an external identity provider (IdP) during OpenID Connect (OIDC) sign-in after the browser interaction returns an authorization code.

appgate.signin.external_provider.waiting_for_user_input

Measures the time that the user takes to complete an external IdP browser interaction during OIDC or Security Assertion Markup Language (SAML) sign-in.

appgate.signin.gateway

Establishes the tunnel from the client to a Gateway during Gateway Connect. The client creates this span.

appgate.signin.initialize

Fetches the IdP and Controller details that the client needs before authentication.

appgate.signin.mfa

Performs the multifactor authentication (MFA) step of sign-in.

appgate.signin.mfa.challenge

Requests or verifies an MFA challenge.

appgate.signin.mfa.waiting_for_user_input

Measures the time that the user takes to enter or approve an MFA challenge.

appgate.signin.name_resolution

Resolves names during Gateway Connect.

appgate.signin.session_creation

Establishes the authorized session on the Gateway during Gateway Connect.

appgate.signin.tcp_connect

Opens the TCP connection during Gateway Connect.

appgate.signin.tls_handshake

Performs the Transport Layer Security (TLS) handshake during Gateway Connect.

appgate.signin.vpn_certificate

Issues the client certificate that the client uses to establish tunnels to Gateways.

appgate.signin.vpn_certificate.generate_key_pair

Generates the local client key pair for VPN certificate issuance.

appgate.signin.vpn_driver.connect

Starts the local VPN driver tunnel on the client during sign-in.

appgate.signout

Represents the root span for an AppGate sign-out flow. The appgate.signin.id attribute correlates this span with the sign-in that it ends.