Telemetry

microgateway.airlock.com/v1alpha1

Telemetry defines the telemetry configuration (logging, metrics & tracing).

apiVersion: microgateway.airlock.com/v1alpha1
kind: Telemetry
metadata:
  name: telemetry-example
spec:
  logging:
    accessLog:
      format:
        json:
          "@timestamp": "%START_TIME(%Y-%m-%dT%T.%3f%z)%"
          ecs:
            version: "8.5"
          log:
            logger: "access"
            level: "info"
          event:
            kind: "event"
            category: [ "web" ]
            type: "%EVENT_TYPE%"
            module: "envoy"
            dataset: "envoy.access"
            outcome: "success"
            start: "%START_TIME(%Y-%m-%dT%T.%3f%z)%"
            end: "%END_TIME(%Y-%m-%dT%T.%3f%z)%"
            duration: "%DURATION_IN_NANOSECONDS%"
          airlock:
            access_control: "%ACCESS_CONTROL%"
            actions:
              block: "%BLOCK_ACTION%"
              header_rewrites: "%HEADER_REWRITES%"
              log_only: "%LOG_ONLY_ACTIONS%"
            http:
              request:
                accept_language: "%REQ(ACCEPT-LANGUAGE):100%"
                correlation_id: "%DYNAMIC_METADATA(com.airlock.microgateway.telemetry:correlation_id)%"
              response:
                redirect_url: "%RESP(LOCATION):1000%"
              session:
                id: "%SESSION_ID%"
            log_correlation: "%LOG_CORRELATION%"
            summary:
              action: "%SUMMARY_ACTION%"
              details: "%RESPONSE_CODE_DETAILS%"
              flags: "%RESPONSE_FLAGS%"
            upstream:
              destination:
                ip: "%UPSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%"
                port: "%UPSTREAM_REMOTE_PORT%"
              http:
                version: "%UPSTREAM_HTTP_VERSION%"
              tls:
                peer:
                  issuer: "%UPSTREAM_PEER_ISSUER%"
                  subject: "%UPSTREAM_PEER_SUBJECT%"
          destination:
            ip: "%DOWNSTREAM_LOCAL_ADDRESS_WITHOUT_PORT%"
            port: "%DOWNSTREAM_LOCAL_PORT%"
          http:
            request:
              body:
                bytes: "%BYTES_RECEIVED%"
              bytes: "%REQUEST_HEADERS_AND_BODY_BYTES%"
              id: "%STREAM_ID%"
              method: "%REQ(:METHOD):100%"
              mime_type: "%REQ_MIME_TYPE:500%"
              referrer: "%REQ(REFERER):1000%"
            response:
              body:
                bytes: "%BYTES_SENT%"
              bytes: "%RESPONSE_HEADERS_AND_BODY_BYTES%"
              mime_type: "%RESP_MIME_TYPE:500%"
              status_code: "%RESPONSE_CODE%"
            version: "%HTTP_VERSION%"
          network:
            forwarded_ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%"
          observer:
            product: "Airlock Microgateway"
            type: "waap"
            vendor: "Ergon Informatik AG"
            version: "%ENVIRONMENT(ENGINE_VERSION)%"
          source:
            ip: "%DOWNSTREAM_DIRECT_REMOTE_ADDRESS_WITHOUT_PORT%"
            port: "%DOWNSTREAM_DIRECT_REMOTE_PORT%"
          url:
            domain: "%HTTP_HOST:500%"
            path: "%REQ_WITHOUT_QUERY(:PATH):1000%"
            query: "%REQ_QUERY(:PATH):1000%"
          user_agent:
            original: "%REQ(USER-AGENT):500%"
          # Additional log keys under 'custom'.
          custom:
            downstream:
              # Log TLS attributes of the downstream connection.
              tls:
                protocol: "%DOWNSTREAM_TLS_VERSION%"
                cipher: "%DOWNSTREAM_TLS_CIPHER%"
                session_id: "%DOWNSTREAM_TLS_SESSION_ID%"
              # Log the direct remote ip address and port.
              direct_remote_address:
                ip: "%DOWNSTREAM_DIRECT_REMOTE_ADDRESS_WITHOUT_PORT%"
                port: "%DOWNSTREAM_DIRECT_REMOTE_PORT%"
            http:
              request:
                # Log the request header 'Cookie'.
                cookie: "%REQ(cookie):500%"
  correlation:
    # Enable correlation id logging based on a custom header.
    idSource:
      header:
        name: X-Request-Id

apiVersion: microgateway.airlock.com/v1alpha1
kind: Telemetry
metadata:
  name: default
spec: 
  logging: 
    accessLog: 
      format: 
        json: 
          "@timestamp": "%START_TIME(%Y-%m-%dT%T.%3f%z)%"
          ecs:
            version: "8.5"
          log:
            logger: "access"
            level: "info"
          event:
            kind: "event"
            category: [ "web" ]
            type: "%EVENT_TYPE%"
            module: "envoy"
            dataset: "envoy.access"
            outcome: "success"
            start: "%START_TIME(%Y-%m-%dT%T.%3f%z)%"
            end: "%END_TIME(%Y-%m-%dT%T.%3f%z)%"
            duration: "%DURATION_IN_NANOSECONDS%"
          airlock:
            access_control: "%ACCESS_CONTROL%"
            actions:
              block: "%BLOCK_ACTION%"
              header_rewrites: "%HEADER_REWRITES%"
              log_only: "%LOG_ONLY_ACTIONS%"
            http:
              request:
                accept_language: "%REQ(ACCEPT-LANGUAGE):100%"
                correlation_id: "%DYNAMIC_METADATA(com.airlock.microgateway.telemetry:correlation_id)%"
              response:
                redirect_url: "%RESP(LOCATION):1000%"
              session:
                id: "%SESSION_ID%"
            log_correlation: "%LOG_CORRELATION%"
            summary:
              action: "%SUMMARY_ACTION%"
              details: "%RESPONSE_CODE_DETAILS%"
              flags: "%RESPONSE_FLAGS%"
            upstream:
              destination:
                ip: "%UPSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%"
                port: "%UPSTREAM_REMOTE_PORT%"
              http:
                status_code: "%UPSTREAM_RESPONSE_CODE%"
                version: "%UPSTREAM_HTTP_VERSION%"
              tls:
                cipher: "%UPSTREAM_TLS_CIPHER%"
                version: "%CEL(upstream.tls_version == 'TLSv1.3' ? 1.3 : upstream.tls_version == 'TLSv1.2' ? 1.2 : upstream.tls_version == 'TLSv1.1' ? 1.1 : (upstream.tls_version == 'TLSv1' || upstream.tls_version == 'TLSv1.0') ? 1.0 : null)%"
                version_protocol: "%CEL((upstream.tls_version == 'TLSv1.3' || upstream.tls_version == 'TLSv1.2' || upstream.tls_version == 'TLSv1.1' || upstream.tls_version == 'TLSv1' || upstream.tls_version == 'TLSv1.0') ? 'tls' : null)%"
                peer:
                  hash:
                    sha256: "%CEL(upstream.sha256_peer_certificate_digest)%"
                  issuer: "%UPSTREAM_PEER_ISSUER%"
                  subject: "%UPSTREAM_PEER_SUBJECT%"
          destination:
            ip: "%DOWNSTREAM_LOCAL_ADDRESS_WITHOUT_PORT%"
            port: "%DOWNSTREAM_LOCAL_PORT%"
          http:
            request:
              body:
                bytes: "%BYTES_RECEIVED%"
              bytes: "%REQUEST_HEADERS_AND_BODY_BYTES%"
              id: "%STREAM_ID%"
              method: "%REQ(:METHOD):100%"
              mime_type: "%REQ_MIME_TYPE:500%"
              referrer: "%REQ(REFERER):1000%"
            response:
              body:
                bytes: "%BYTES_SENT%"
              bytes: "%RESPONSE_HEADERS_AND_BODY_BYTES%"
              mime_type: "%RESP_MIME_TYPE:500%"
              status_code: "%RESPONSE_CODE%"
            version: "%HTTP_VERSION%"
          network:
            forwarded_ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%"
          observer:
            product: "Airlock Microgateway"
            type: "waap"
            vendor: "Ergon Informatik AG"
            version: "%ENVIRONMENT(ENGINE_VERSION)%"
          source:
            ip: "%DOWNSTREAM_DIRECT_REMOTE_ADDRESS_WITHOUT_PORT%"
            port: "%DOWNSTREAM_DIRECT_REMOTE_PORT%"
          tls:
            cipher: "%DOWNSTREAM_TLS_CIPHER%"
            client:
              hash:
                sha256: "%DOWNSTREAM_PEER_FINGERPRINT_256%"
              issuer: "%DOWNSTREAM_PEER_ISSUER%"
              ja3: "%TLS_JA3_FINGERPRINT%"
              ja4: "%TLS_JA4_FINGERPRINT%"
              server_name: "%REQUESTED_SERVER_NAME%"
              subject: "%DOWNSTREAM_PEER_SUBJECT%"
            version: "%CEL(connection.tls_version == 'TLSv1.3' ? 1.3 : connection.tls_version == 'TLSv1.2' ? 1.2 : connection.tls_version == 'TLSv1.1' ? 1.1 : (connection.tls_version == 'TLSv1' || connection.tls_version == 'TLSv1.0') ? 1.0 : null)%"
            version_protocol: "%CEL((connection.tls_version == 'TLSv1.3' || connection.tls_version == 'TLSv1.2' || connection.tls_version == 'TLSv1.1' || connection.tls_version == 'TLSv1' || connection.tls_version == 'TLSv1.0') ? 'tls' : null)%"
          url:
            domain: "%HTTP_HOST:500%"
            path: "%REQ_WITHOUT_QUERY(:PATH):1000%"
            query: "%REQ_QUERY(:PATH):1000%"
          user_agent:
            original: "%REQ(USER-AGENT):500%"
  correlation: 
    request: 
      alterRequestID: true
      allowDownstreamRequestID: false

Telemetry

Field	Description	Type	Required	Default	Allowed Values
metadata	defines the resource’s metadata	ObjectMeta	yes
spec	defines the desired telemetry configuration.	object	no

Telemetry.spec

Field	Description	Type	Required	Default	Allowed Values
correlation	defines the correlation aspects of Telemetry.	object	no
logging	defines the logging aspects of Telemetry.	object	no

Telemetry.spec.correlation

Field	Description	Type	Required	Default	Allowed Values
idSource	specifies how an external correlation ID should be obtained for a request. If not specified, no correlation ID will be logged.	object	no
request	defines the request related correlation settings of Telemetry.	object	no

Telemetry.spec.correlation.idSource

Field	Description	Type	Required	Default	Allowed Values
header	specifies to extract the correlation ID from a request header. If the header is absent from a request, no correlation ID will be logged.	object	yes

Telemetry.spec.correlation.idSource.header

Field	Description	Type	Required	Default	Allowed Values
name	of the header (case-insensitive) from which to extract the correlation ID.	string	no	`X-Correlation-Id`

Telemetry.spec.correlation.request

Field	Description	Type	Required	Default	Allowed Values
allowDownstreamRequestID	defines whether trace sampling will consider a provided x-request-id.	bool	no	`false`	`true`, `false`
alterRequestID	defines whether to alter the UUID to reflect the trace sampling decision. If disabled no modification to the UUID will be performed, this may break tracing in the upstream.	bool	no	`true`	`true`, `false`

Telemetry.spec.logging

Field	Description	Type	Required	Default	Allowed Values
accessLog	defines the access log settings of Telemetry.	object	no

Telemetry.spec.logging.accessLog

Field	Description	Type	Required	Default	Allowed Values
format	defines the Access Log format of the sidecar.	object	no

Telemetry.spec.logging.accessLog.format

Field	Description	Type	Required	Default	Allowed Values
json	defines the Access Log format as JSON.	unstructured	no