Skip to content

Ecommerce Platform Runbook

Overview

The ecommerce platform has quite a few moving parts. Each subsystem will have its own more focused set of runbook tasks.

For an overview of ecommerce customer account/index details, see Ecommerce Customer Details. For more details about accounts and indexes, see Polo.

Alarms

If something goes wrong, an alarm should be triggered. If this just happened to you, jump to the corresponding page to learn more.

prod-EcomMonitoringServiceAlarm

EcomQueueBacklogIncreasing-{system_account_id}-{index_name}

Historical incident reports (PIR-style analysis) are tracked outside runbooks: FashionNova Queue Age Spike (2026-02-17)

Onboarding

Enable merchandising for an index

Enable agentic search and agentic chat for an index

Enable ETL pipeline to push automated updates to an index

If a customer already has ETL set up, but they now have a new index, follow this runbook:

Reconnect pixel ETL pipeline to an existing customer’s new index

Config

Setting up exact match boosters (for example, boost on title field)

Indexes

Set account to use custom Marqtune model

Recommendations

Set up For-You recommendations

Check For-You is working

View Index Details

  • View: Ecom Index endpoints, UI

Operations

Convert classic index to ecom

Create new index with different settings

Change the account-level (sk = INDEX#DEFAULT_CONFIG) create_index_config in the index settings table before calling POST /indexes

Modify index infra

The infra and edit options don’t appear in the Console UI any more. For now, just call the PUT index API on the Controller.

A separate Vespa schema is provided to support typeahead search (search suggestion) feature in e-comm API. The data ingestion process for his schema is described in this runbook: Phase 1: Extract the query data from Pixel account

Getting customer config in CloudFlare

Go to: prod-ecom-api → Bindings

Click on prod-search-proxy-kv

Search key by prefix: -

Click on it to show the search config in CF

Indexing

Redrive Ecom Indexing Pipeline

Scale ecom indexing throughput

Forking writes between indexes

Jobs

  • View: Endpoints, UI
    • https://docs.marqo.ai/latest/home/manage-index/manage-jobs/
    • UI
  • Reset jobs and clear blocked queues: there’s a DELETE endpoint that probably won’t be around for long.

Viewing metrics in AWS

https://www.notion.so/Get-dashboard-for-an-index-14a75d43da4c80668cdfce0e94f4003c

Debugging

Use this for finding out things like “why did index creation not work with an unhelpful error?”

Logs for the Ecom API are located in the account 023568249301 Cloud controller

In general, when you’re looking for a specific error, the following Logs Insights query is helpful

fields @timestamp, @message
| filter @message like /<enter your substring to search for here>/
| sort @timestamp desc
| limit 50

Remember to select to appropriate log group and time range to look into.

Screenshot 2025-11-07 at 3.46.27 PM.png

This will yield results with each giving us the field logStream . To look further into the the error, navigate to the log group (/aws/lambda/prod-ShopifyAppAdminFunction for example), then search for the desired log stream using the returned logStream value.

Log Groups for Specific Operations

Debugging index creation

  • Note, sometimes the index name isn’t able to be found in the logs for index creation failure
  • For example, the following query worked better, which used the error message:
fields @timestamp, @message
| filter @message like /Invalid request parameters/
| sort @timestamp desc
| limit 50

Reindexing