You can use traffic splitting to specify a percentage distribution of traffic across two or more of the versions within a service. Splitting traffic allows you to conduct A/B testing between your versions and provides control over the pace when rolling out features.
Traffic splitting is applied to URLs that do not explicitly target a version. For example, the following URLs split traffic because they target all the available versions within the specified service:
[MY_PROJECT].appspot.com- Distributes traffic to versions of the
[MY_SERVICE].[MY_PROJECT].appspot.com- Distributes traffic to versions of the
For information about how requests reach a version, see How Requests are Routed.
Before you begin
Before you can configure traffic to a version, ensure that your user account includes the required privileges.
Avoiding caching issues
Before you turn on traffic splitting, you might want to account for potential caching problems. Caching issues can exist for any App Engine application, especially when deploying a new version. Traffic splitting often makes subtle caching problems more apparent.
For example, assume you are splitting traffic between two versions, A and B, and some external cacheable resource changed between versions, for example, a CSS file. Now assume that a client makes a request and the response contains an external reference to the cached file. The local HTTP cache will retrieve the file if it's in the cache, regardless of which version of the file is cached and which version of the application sent the response. The cached resource could be incompatible with the data that was sent in the response.
To avoid caching problems:
For dynamic resources, set both the Cache-Control and Expires headers. These headers tell proxies that the resource is dynamic. It is best to set both headers, since not all proxy servers support the HTTP/1.1
For cacheable static resources that vary between versions, change the resource's URL between versions. If the static resources are served from different URLs, then both versions can happily co-exist in proxy servers and browser caches.
You can also have your app set the Vary:
header so that the uniqueness of a resource is computed by combining the cookies
and the URL for the request. However, this approach increases the burden on
cache servers. There are 1000 possible values of
GOOGAPPUID, and hence 1000
possible entries for each URL for your app. Depending on the load on the proxies
between your users and your app, this can decrease the cache hit rate. Also,
note that for the 24 hours after adding a new batch of users to a version, they
might still see cached resources. However, using
Vary: Cookie can make it
easier to rename static resources that are changing between versions.
Vary: Cookie technique doesn't work in all circumstances. In general, if
your app is using cookies for other purposes, you must consider how this
affects the burden on proxy servers. If
codeninja had its own cookie that had
100 possible values, then the space of all possible cache entries becomes a
very big number (100 * 1000 = 100,000). In the worst case, there is a unique
cookie for every user. Two common examples of this are Google Analytics
__utma) and SiteCatalyst (
s_vi). In these cases, every user gets a unique
copy, which severely degrades cache performance and can also increase the
billable instance hours consumed by your app.
Splitting traffic across multiple versions
When you have specified two or more versions for splitting, you must choose whether to split traffic by using either an IP address or HTTP cookie. It's easier to set up an IP address split, but a cookie split is more precise. For more information, see IP address splitting and Cookie splitting.
To split traffic in the Cloud Console, go to the Versions page:
- Select one or more versions to which you want to split traffic.
- Click Split traffic and then specify:
- The method that you want to use for splitting traffic.
- The percentage of traffic each version should receive.
After installing the Google Cloud SDK, you run the following command to split traffic across multiple versions, for example:
gcloud app services set-traffic [MY_SERVICE] --splits [MY_VERSION1]=[VERSION1_WEIGHT],[MY_VERSION2]=[VERSION2_WEIGHT] --split-by [IP_OR_COOKIE]
For details and additional options, see the
gcloud app services
To programmatically migrate traffic, you can use the Admin API, see Migrating and Splitting Traffic for details.
IP address splitting
If you choose to split traffic to your application by IP address, when the application receives a request, it hashes the IP address to a value between 0–999, and uses that number to route the request.
IP address splitting has some significant limitations:
- IP addresses are reasonably sticky, but are not permanent. Users connecting from cell phones might have a shifting IP address throughout a single session. Similarly, a user on a laptop might be moving from home to a cafe to work, and will also shifting through IP addresses. As a result, the user might have an inconsistent experience with your app as their IP address changes.
- Because IP addresses are independently assigned to versions, the resulting traffic split will differ somewhat from what you specify. Although, as your application receives more traffic, the closer the actual split gets to your target. For example, if you ask for 5% of traffic to be delivered to an alternate version, the initial percent of traffic to the version might actually be between 3–7% but eventually averages closer to your target 5%.
- If you need to send internal requests between apps, you should use cookie splitting instead. Requests that are sent between apps running on Google's cloud infrastructure, originate from a small number of IP addresses which are likely all assigned to the same version. Therefore, all internal requests might behave similar to requests sent from a single IP address, meaning that those requests are all routed to the same version. As a result, internal requests do not closely respect the percentages that you set for your IP-based traffic splits. For example, if you set a version to receive 1% of all the traffic to your app and the Google cloud infrastructure addresses were coincidently assigned to that version, then the actual result might far exceed 1% because all the internal requests are always routed to the assigned version. Requests sent to your app from outside of Google's cloud infrastructure will work as expected since they originate from a varied distribution of IP addresses.
If you choose to split traffic to your application by cookies,
the application looks in the
HTTP request header
for a cookie named
GOOGAPPUID, which contains a value between 0–999:
- If the cookie exists, the value is used to route the request.
- If there is no such cookie, the request is routed randomly.
If the response does not contain the
GOOGAPPUID cookie, the app first
GOOGAPPUID cookie with a random value between 0–999 before
it is sent.
Using cookies to split traffic makes it easier to accurately assign users to versions. The precision for traffic routing can reach as close as 0.1% to the target split. Although, cookie splitting has the following limitations:
If you are writing a mobile app or running a desktop client, it needs to manage the
GOOGAPPUIDcookies. For example, when a
Set-Cookieresponse header is used, you must store the cookie and include it with each subsequent request. Browser-based apps already manage cookies in this way automatically.
Splitting internal requests requires extra work. All user requests that are sent from within Google's cloud infrastructure, require that you forward the user's cookie with each request. For example, you must forward the user's cookie in requests sent from your app to another app, or to itself. Note that it is not recommended to send internal requests if those requests don't originate from a user.
Disabling traffic splitting
To disable traffic splitting, you migrate all traffic to a single version.