This package defines the Mixer API that the sidecar proxy uses to perform precondition checks, manage quotas, and report telemetry.
Mixer provides three core features:
Precondition Checking. Enables callers to verify a number of preconditions before responding to an incoming request from a service consumer. Preconditions can include whether the service consumer is properly authenticated, is on the service’s whitelist, passes ACL checks, and more.
Quota Management. Enables services to allocate and free quota on a number of dimensions, Quotas are used as a relatively simple resource management tool to provide some fairness between service consumers when contending for limited resources. Rate limits are examples of quotas.
Telemetry Reporting. Enables services to report logging and monitoring. In the future, it will also enable tracing and billing streams intended for both the service operator as well as for service consumers.
rpc Check(CheckRequest) returns (CheckResponse)
Checks preconditions and allocate quota before performing an operation. The preconditions enforced depend on the set of supplied attributes and the active configuration.
rpc Report(ReportRequest) returns (ReportResponse)
Reports telemetry, such as logs and metrics. The reported information depends on the set of supplied attributes and the active configuration.
Attributes represents a set of typed name/value pairs. Many of Mixer’s API either consume and/or return attributes.
Istio uses attributes to control the runtime behavior of services running in the service mesh. Attributes are named and typed pieces of metadata describing ingress and egress traffic and the environment this traffic occurs in. An Istio attribute carries a specific piece of information such as the error code of an API request, the latency of an API request, or the original IP address of a TCP connection. For example:
request.path: xyz/abc request.size: 234 request.time: 12:34:56.789 04/17/2017 source.ip: 192.168.0.1 target.service: example
A given Istio deployment has a fixed vocabulary of attributes that it understands. The specific vocabulary is determined by the set of attribute producers being used in the deployment. The primary attribute producer in Istio is Envoy, although specialized Mixer adapters and services can also generate attributes.
The common baseline set of attributes available in most Istio deployments is defined here.
Attributes are strongly typed. The supported attribute types are defined by ValueType. Each type of value is encoded into one of the so-called transport types present in this message.
Defines a map of attributes in uncompressed format. Following places may use this message: 1) Configure Istio/Proxy with static per-proxy attributes, such as source.uid. 2) Service IDL definition to extract api attributes for active requests. 3) Forward attributes from client proxy to server proxy for HTTP requests.
Specifies one attribute value with different type.
Defines a string map.
Used to get a thumbs-up/thumbs-down before performing an action.
parameters for a quota allocation
The response generated by the Check method.
Expresses the result of a precondition check.
Expresses the result of a quota allocation.
Defines a list of attributes in compressed format optimized for transport. Within this message, strings are referenced using integer indices into one of two string dictionaries. Positive integers index into the global deployment-wide dictionary, whereas negative integers index into the message-level dictionary instead. The message-level dictionary is carried by the
words field of this message, the deployment-wide dictionary is determined via configuration.
Describes the attributes that were used to determine the response. This can be used to construct a response cache.
Describes a single attribute match.
How an attribute’s value was matched
should not occur
match when attribute doesn’t exist
match when attribute value is an exact byte-for-byte match
match when attribute value matches the included regex
Used to report telemetry after performing one or more actions.
Used to carry responses to telemetry reports
A map of string to string. The keys and values in this map are dictionary indices (see the Attributes message for an explanation)
Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. The error model is designed to be:
- Simple to use and understand for most users
- Flexible enough to meet unexpected needs
Status message contains three pieces of data: error code, error message, and error details. The error code should be an enum value of google.rpc.Code, but it may accept additional error codes if needed. The error message should be a developer-facing English message that helps developers understand and resolve the error. If a localized user-facing error message is needed, put the localized message in the error details or localize it in the client. The optional error details may contain arbitrary information about the error. There is a predefined set of error detail types in the package
google.rpc that can be used for common error conditions.
Status message is the logical representation of the error model, but it is not necessarily the actual wire format. When the
Status message is exposed in different client libraries and different wire protocols, it can be mapped differently. For example, it will likely be mapped to some exceptions in Java, but more likely mapped to some error codes in C.
The error model and the
Status message can be used in a variety of environments, either with or without APIs, to provide a consistent developer experience across different environments.
Example uses of this error model include:
Partial errors. If a service needs to return partial errors to the client, it may embed the
Statusin the normal response to indicate the partial errors.
Workflow errors. A typical workflow has multiple steps. Each step may have a
Statusmessage for error reporting.
Batch operations. If a client uses batch request and batch response, the
Statusmessage should be used directly inside batch response, one for each error sub-response.
Asynchronous operations. If an API call embeds asynchronous operation results in its response, the status of those operations should be represented directly using the
Logging. If some API errors are stored in logs, the message
Statuscould be used directly after any stripping needed for security/privacy reasons.