Opsphere
← All articles

Akamai CDN: How to Investigate Edge Issues in Production

Akamai CDN: How to Investigate Edge Issues in Production

Abstract edge and origin investigation layers

Akamai CDN is a globally distributed network of edge servers that sits between your users and your origin, caching content and absorbing traffic. When production breaks behind it, the hard part is rarely Akamai itself. It is deciding whether the fault lives at the edge (property rules, caching, redirects, WAF) or behind it (origin, application, DNS, a recent deployment). This guide explains how the platform handles a request, then gives SRE, DevOps, platform engineering and security teams a repeatable workflow, a troubleshooting table and the conditions to verify before anyone changes a rule.

Opsphere
opsphere.io
Investigate Edge Issues With Full Context
Opsphere brings Akamai evidence together with cloud, Kubernetes, observability and CI/CD context in a read-only interface.
Explore Opsphere

TL;DR

  • Problem: Akamai incidents look the same from the outside (errors, stale pages, redirect loops), but the cause can sit in a property rule, the cache, the origin, DNS or a deploy.
  • Key takeaway: Classify the failing request first. Where it was served from, which rule matched and whether the edge reached the origin separate most edge problems from everything else in minutes.
  • Next step: Collect edge evidence and cloud, Kubernetes, observability and CI/CD evidence for the same time window before touching any configuration.
  • How Opsphere fits: Opsphere is a read-only operational intelligence layer that lets you query and correlate Akamai evidence with the rest of your stack. It does not replace Akamai or change its configuration.

Table of Contents

What Akamai CDN does, in operational terms

A content delivery network (CDN) is a group of geographically distributed servers that bring content closer to users. Akamai describes its network as more than 4,100 locations across 120+ countries, delivering websites, apps, APIs, video and software. Akamai was founded in 1998 and commercialized the first large-scale CDN.

For an on-call engineer, three roles matter:

  • Reverse proxy. In many deployments the CDN sits between end users and origin infrastructure, managing requests and protecting the origin.
  • Cache. Edge servers answer from cache when they can and go back to the origin when they cannot.
  • Policy point. Property rules, redirects and security controls such as the WAF run at the edge, before your application sees anything.

That last role is why edge incidents are tricky. A request can be rejected, redirected or rewritten without a single line appearing in your application logs.

How a request flows through Akamai

Knowing the path tells you which evidence to pull at each hop.

  1. DNS. The hostname resolves to an edge hostname. Per Akamai’s docs, a request resolves to an edge hostname assigned to the actual hostname, and that edge hostname directs it to a property.
  2. Edge server selection. Akamai uses proprietary mapping to pick the best edge server. Where Edge IP Binding is used, Anycast provides a fixed set of IP addresses.
  3. Property rules. The property determines how content is delivered: caching, redirects, header changes, origin selection and more.
  4. Cache lookup. If a fresh copy exists, the edge responds. If not, it goes forward to the origin.
  5. Origin fetch. The edge server stands in for your site, while the origin is where the content originates.

Every incident maps onto one of these steps. The job is to find which one.

Edge or not edge: how to tell

Start with where the failing response was generated. Three questions do most of the work.

Did the response come from Akamai at all? Error pages, headers and reference numbers identify the source. If the response never carried Akamai headers, the request may have bypassed the CDN entirely, which points to DNS or a hostname that is not mapped to the property.

Was it served from cache, or fetched from the origin? Akamai’s debug headers answer this. Sending the Pragma request header akamai-x-cache-on returns an X-Cache response header showing values such as TCP_HIT (fresh in cache) and TCP_MISS (fetched from an origin server). A string of misses on content you expect to be cached suggests a caching rule or cache-key problem. A hit that serves outdated content suggests TTL or purge problems.

Which side of the edge is failing? Akamai’s Edge Diagnostics can split error statistics by direction: EDGE_ERRORS covers traffic between a customer and an edge server, ORIGIN_ERRORS between the edge server and the origin. That split is the quickest way to separate an edge-side fault from an origin-side one.

A rough decision rule:

  • Errors only on the client-to-edge leg: look at WAF events, property rules, certificates and redirects.
  • Errors only on the edge-to-origin leg: look at origin reachability, load balancers, security groups, health and deployments.
  • Errors on both: look for a shared cause, such as a bad deploy that changed headers the edge depends on.

Step-by-step investigation workflow

Follow the same order every time. It keeps the investigation evidence-based and stops people from changing a property while the real cause sits elsewhere.

Step 1: Pin down one failing request

Capture a specific URL, timestamp (with time zone), client behavior and status code. Collect the Akamai reference number if an error page showed one, plus any request ID your application logs. A single concrete request beats a vague symptom like “the site is slow.”

Step 2: Establish the blast radius

Is it one path, one hostname, one geography or everything? Path-specific failures usually implicate a property rule or a behavior tied to that path. Global failures lean toward the origin, DNS or a certificate.

Step 3: Read the cache story

Request the URL with debug headers and note the X-Cache value, the cache key and the remaining TTL. By default, Akamai edge servers only cache content requested via GET, and headers such as Vary can influence cacheability. A Vary header that explodes the number of cache variants is a classic reason for unexpected misses.

Step 4: Check redirects and rule matches

Follow the redirect chain hop by hop. Loops often come from two layers each enforcing a different canonical rule: an edge rule forcing HTTPS or a hostname, and an origin or load balancer doing the opposite. Compare what the property is configured to do with what the origin returns on its own.

Step 5: Check origin reachability

Test the origin directly, bypassing the CDN, from a network position similar to the edge. Check DNS for the origin hostname, TLS certificate hostname match, security group and firewall allowlists, and load balancer target health. Timeouts between edge and origin look identical to an overloaded origin unless you check the origin’s own metrics.

Step 6: Review WAF and security events

If requests are being denied, find the matching security event and rule. Then check whether the traffic is attack traffic, a legitimate client hitting a rule, or your own health checks and integrations being blocked. Security and SRE teams should read the same event, since a block can masquerade as an origin error. Opsphere’s write-up on tracing WAF blocks and origin errors together walks through this correlation.

Step 7: Line up the change timeline

Compare the incident start with property activations, application deploys, Kubernetes rollouts, infrastructure changes and DNS edits. Most production incidents follow a change. The question is which layer changed first.

Step 8: State a hypothesis and test it

Write down one hypothesis, such as “the new release removed a Cache-Control header, so the edge stopped caching,” and the evidence that would prove or disprove it. Test several hypotheses in parallel when you can, but keep each tied to evidence.

Troubleshooting table

Symptom Likely layer Evidence to check Typical cause
Stale content after a release Cache X-Cache value, TTL, purge history, deploy time TTL too long, purge not issued or incomplete
Low cache hit ratio on static assets Property rules / origin headers Cache key, Vary header, Cache-Control from origin Origin sending no-store, query strings in the cache key
5xx errors on cache misses only Origin ORIGIN_ERRORS split, origin metrics, load balancer health Origin overloaded or unreachable from edge
Redirect loop Property rules and origin Redirect chain, rule match, origin response without CDN Edge and origin enforcing conflicting canonical rules
403 on specific clients or paths WAF / security Security event, rule ID, client IP, request pattern A rule matching legitimate traffic
Timeouts to origin Network / origin Origin DNS, security groups, TLS handshake, target health Firewall allowlist missing edge IPs, expired origin certificate
Users reach old infrastructure DNS Resolution of hostname, edge hostname mapping, TTL Hostname not mapped to the edge, stale DNS record
Errors begin right after a deploy Deployment Rollout history, config diff, header changes App change altered headers, paths or auth the edge relies on
Regional problems only Edge mapping / network Failing geographies, edge server selection, origin logs by region Routing or regional capacity issue; escalate with evidence

Treat the table as a place to start looking, not a verdict. Each row needs confirming evidence before you act.

Caching behavior: where most surprises come from

Caching issues generate more edge tickets than any other class, because the behavior is a product of rules, origin headers and time.

When you suspect a cache problem, compare three times: when the origin content changed, when the purge (if any) ran, and when the user saw the old version. The gap usually explains the symptom.

Origin reachability and the Anycast caveat

If the edge cannot fetch from the origin, users see errors on misses while cached objects keep working. That pattern, healthy cached paths with failing uncached ones, is a strong signal to move the investigation behind the edge.

Check these in order:

  1. Does the origin hostname resolve correctly, and to what?
  2. Does the origin certificate match the hostname the edge uses, and is it valid?
  3. Do security groups, firewalls and load balancers allow traffic from Akamai’s edge?
  4. Are load balancer targets healthy, and are pods ready in Kubernetes?
  5. Did CPU, memory, connection or database limits change at the time of failure?

A note on IP-based routing: Anycast lets server groups in different locations share a CIDR block, but it does not consider server load, capacity or availability. Anycast alone will not steer around a degraded location, so regional symptoms need evidence from more than one vantage point.

Verification conditions before remediation

A fix applied to the wrong layer wastes time and can widen the incident. Before changing a property, purging, rolling back or editing a WAF rule, confirm that:

  • The failure is reproducible or clearly timestamped. You can name a request that fails and one that succeeds.
  • The layer is identified. Edge-to-origin and client-to-edge error splits point in the same direction as the other evidence.
  • A change correlates with the start. A property activation, deploy, certificate event or DNS change lines up with the first error. If none does, look for load or an external dependency.
  • The origin was tested directly. You know whether it behaves correctly without the CDN in front.
  • The remediation is scoped. You know which paths, hostnames or rules it affects, and what a rollback looks like.
  • Compliance and security owners agree when the fix touches caching of sensitive content or loosens a WAF rule.
  • Success is measurable. You have the metric, such as error rate on ORIGIN_ERRORS or the X-Cache value on the affected URL, that proves recovery.

If any condition fails, keep investigating. A purge or rule change made on a hunch is hard to reason about later.

Practical examples

These are illustrative patterns, not customer stories.

Example 1: Fixed bug, old page. A team ships a fix, yet users still see the bug. The X-Cache header shows a hit on HTML with a long TTL, and the deploy time is later than the last purge. The edge is behaving as configured. The remediation is a targeted purge plus a review of the HTML TTL, after confirming the origin now returns the fixed content.

Example 2: Errors only on misses. Error rates climb while cached assets load fine. The edge-to-origin split shows the failures, the load balancer reports unhealthy targets, and a Kubernetes rollout started minutes earlier with failing readiness probes. This is an origin and deployment problem. Changing Akamai rules would do nothing, and the rollback happens in your CI/CD and cluster.

Example 3: Sudden 403s. A partner integration starts getting denied. The security event shows a WAF rule matching a new request pattern introduced in the partner’s latest client version. The origin is healthy and never sees the requests. This is an edge policy issue, and the fix is a reviewed rule exception, owned jointly by security and SRE.

Example 4: Redirect loop after a TLS change. A load balancer begins redirecting HTTP to HTTPS while the property forwards to the origin over HTTP. Each side thinks it is right. Comparing the property’s origin protocol with the origin’s redirect behavior reveals the conflict.

Practical examples

Where Opsphere fits

The workflow above needs evidence from many places: Akamai, cloud accounts, clusters, observability, pipelines and code. Pulling it together by hand is where incident time disappears.

Opsphere is an AI-powered operational intelligence platform that unifies operational context across AWS, Kubernetes, observability, CI/CD, security and engineering tools. Akamai evidence joins that picture, so you can ask a question and see edge events next to the origin, cluster and deployment data that explain them. Opsphere works through read-only operational tools: it connects to your existing systems, keeps each tool as the source of truth, and does not replace Akamai, store its telemetry or change configurations automatically. Changes stay with your team and your normal approval process. You can read about how Opsphere handles access on its security page.

Teams can query through the web client or from the IDE and AI tools they already use through the MCP operational gateway, including with their own model via Bring Your Own AI.

Plans

Opsphere’s Community plan is €0 per month and the Developer plan is €19 per month, so an individual engineer can try the workflow on a real environment. The Team plan is €500 per month and Enterprise is €450 per month, as published on the pricing page. Custom Solutions has no published price.

Opsphere

Monitoring that shortens the next investigation

A few habits make every future Akamai incident faster:

  • Stream edge logs somewhere queryable. Akamai offers DataStream for low-latency log data to third-party platforms and mPulse for real-user measurement. Real-user data shows the impact, and logs show the cause.
  • Record property activations in the same timeline as deploys and infrastructure changes.
  • Keep a cache-behavior inventory. Note which paths are cacheable, their TTLs and who owns them.
  • Alert on the origin side of the edge. Origin error rate and latency catch problems that the cache hides.
  • Write the runbook around the decision rule. Edge leg, origin leg, both. People under pressure follow a short branch better than a long guide.

Adjacent evidence matters too. Opsphere’s guide to checking CloudTrail before chasing logs shows the same change-first habit for AWS-hosted origins.

FAQ

What does CDN stand for, and what is Akamai CDN?

CDN stands for content delivery network: a group of geographically distributed servers that speed up web content delivery by bringing it closer to users. Akamai CDN delivers websites, apps, APIs, video and software through its global edge network, and it also offloads origin traffic and adds security controls.

How do I know if an Akamai problem is the edge or my origin?

Check which leg is failing. Edge Diagnostics can separate errors between the client and the edge from errors between the edge and the origin. Cached content working while uncached content fails points behind the edge. Denials or redirects that never reach your logs point to edge rules or the WAF.

Why is Akamai still serving old content after I deployed?

The edge is probably serving a cached object whose TTL has not expired, or a purge has not been issued or completed. Check the X-Cache header, the TTL on that path and the purge time against your deploy time. Confirm the origin returns the new version before purging.

Can Opsphere change my Akamai configuration?

No. Opsphere is a read-only operational intelligence layer. It lets teams query and correlate Akamai evidence with their cloud, Kubernetes, observability, CI/CD and code systems, and any change is made by your team through your existing process.

Next step: investigate Akamai issues with evidence

If your team spends incident time switching between the Akamai console, cloud dashboards, cluster tools and pipelines, see how Opsphere puts that evidence in one read-only place. Start with the Akamai investigation walkthrough, then compare plans and start free.

Sources

Opsphere
Discuss Your Akamai Investigation
Reach out to discuss how Opsphere can help your team correlate Akamai evidence with operational context across your stack.

This article is provided for general informational purposes only and does not constitute professional, legal, security, or compliance advice. Please evaluate recommendations against your organization’s specific environment and requirements.