Setup e ajuste do OpenSearch no Magento 2.4.8

Desde o 2.4, o Magento não roda sem um motor de busca. A busca do catálogo, a listagem de categorias e a navegação em camadas leem dele, então um cluster OpenSearch lento ou doente aparece como páginas de categoria lentas, resultados de busca vazios e reindexações que falham. Este guia cobre como configuro o OpenSearch para o Magento Open Source e o Adobe Commerce 2.4.8, as configurações que importam e como verificar o que está acontecendo quando algo quebra.

Qual motor e qual versão

Para o 2.4.8, o motor recomendado é o OpenSearch 2.x. A Adobe publica as versões exatas testadas na página de requisitos de sistema de cada release, e eu consulto essa página antes de todo upgrade em vez de confiar na memória. Rodar uma versão major mais nova que a testada é uma fonte comum de erros de mapping durante o reindex.

No Magento o motor é selecionado pelo valor de config catalog/search/engine. Para o OpenSearch o valor é opensearch. Se você atualizou uma loja antiga que usava Elasticsearch, confira esse valor primeiro, porque uma configuração de motor que sobrou gera erros que parecem problemas de conexão.

Conectando o Magento ao OpenSearch

Em uma instalação nova, a conexão é passada ao setup:install:

bin/magento setup:install \
  --search-engine=opensearch \
  --opensearch-host=opensearch \
  --opensearch-port=9200 \
  --opensearch-index-prefix=magento2 \
  --opensearch-timeout=15 \
  --opensearch-enable-auth=1 \
  --opensearch-username=magento \
  --opensearch-password=CHANGE_ME
  # plus your usual database, admin and base URL options

Em uma loja existente, use config:set. Eu prefiro travar esses valores no app/etc/env.php com a flag --lock-env, assim cada ambiente mantém o próprio host e ninguém muda pelo admin por engano.

bin/magento config:set --lock-env catalog/search/engine opensearch
bin/magento config:set --lock-env catalog/search/opensearch_server_hostname opensearch
bin/magento config:set --lock-env catalog/search/opensearch_server_port 9200
bin/magento config:set --lock-env catalog/search/opensearch_index_prefix magento2
bin/magento config:set --lock-env catalog/search/opensearch_server_timeout 15
bin/magento cache:flush config

O admin tem um botão Test Connection em Stores, Configuration, Catalog, Catalog, Catalog Search. Ele só prova que o Magento alcança o cluster. Não diz nada sobre a saúde dos índices.

Index prefix em clusters compartilhados

Se mais de uma instância do Magento aponta para o mesmo cluster, por exemplo staging e um ambiente de feature, dê a cada uma o seu próprio index prefix. Duas lojas escrevendo no mesmo prefix sobrescrevem os índices de produto uma da outra e os sintomas são aleatórios: produtos do catálogo errado, resultados sumindo depois de um reindex no outro ambiente.

Como o Magento nomeia seus índices

O Magento cria um índice de produtos por store view. O índice físico tem um sufixo de versão e um alias aponta para o que está ativo. Durante um reindex completo o Magento monta um índice novo, depois move o alias e apaga o antigo. Isso quer dizer que um reindex completo precisa de espaço para duas cópias do índice de cada loja ao mesmo tempo. Lembre disso ao dimensionar o disco.

curl -s 'http://opensearch:9200/_cat/indices?v&s=index'
curl -s 'http://opensearch:9200/_cat/aliases?v'
curl -s 'http://opensearch:9200/_cluster/health?pretty'

Essas três chamadas respondem a maioria das perguntas. Os índices com o seu prefix devem aparecer listados, cada store view deve ter um alias e a saúde do cluster deve estar green.

Configurações do servidor que importam

Heap da JVM

O OpenSearch roda na JVM e o tamanho do heap é a configuração de maior efeito. Defina mínimo e máximo com o mesmo valor em config/jvm.options ou pelo OPENSEARCH_JAVA_OPTS. A orientação usual é cerca de metade da memória da máquina, deixando o resto para o file cache do sistema operacional, e ficar abaixo de aproximadamente 31 GB para a JVM continuar usando compressed pointers.

-Xms2g
-Xmx2g

A maioria dos catálogos que vejo não precisa de um heap enorme. Algumas centenas de milhares de produtos em poucas store views cabem em alguns gigabytes. Quando o heap é pequeno demais, você vê pausas longas de garbage collection, exceções de circuit breaker durante o reindex e timeouts no storefront.

Clusters de um nó e saúde yellow

Muitas lojas Magento rodam um único nó de OpenSearch. Por padrão, um índice pede uma réplica, e uma réplica nunca pode ficar no mesmo nó que o primary, então o cluster fica yellow. A busca continua funcionando, mas um cluster yellow esconde problemas reais. Em um único nó eu adiciono um index template para que os novos índices do Magento sejam criados com zero réplicas:

curl -s -X PUT 'http://opensearch:9200/_index_template/magento2' \
  -H 'Content-Type: application/json' \
  -d '{
    "index_patterns": ["magento2_*"],
    "template": { "settings": { "number_of_replicas": 0 } }
  }'

Ajuste o padrão ao seu index prefix. Em um cluster real com vários nós, mantenha pelo menos uma réplica.

Disk watermarks

Quando um nó passa do high disk watermark, o OpenSearch para de alocar shards nele, e no flood stage marca os índices como somente leitura. O Magento então falha o reindex com um erro sobre índice bloqueado. Libere o espaço primeiro. Depois remova o bloqueio, se o cluster não o tirou sozinho:

curl -s -X PUT 'http://opensearch:9200/magento2_*/_settings' \
  -H 'Content-Type: application/json' \
  -d '{"index.blocks.read_only_allow_delete": null}'

Plugin de segurança

O OpenSearch vem com um plugin de segurança que habilita TLS e autenticação. Em produção, mantenha ligado e configure usuário e senha no Magento. Em um setup local com Docker, muitos devs o desativam para simplificar. Isso é aceitável em um notebook e nunca em um servidor acessível de fora.

Acelerando o catalogsearch_fulltext

O indexer de full text costuma ser o mais lento. Algumas coisas fazem diferença mensurável.

• Menos atributos pesquisáveis. Todo atributo com Use in Search igual a Yes entra no documento do produto. As lojas acumulam dezenas de atributos pesquisáveis que nenhum cliente digita na caixa de busca. Revise-os, veja as boas práticas de atributos de produto.
• Update by Schedule. Com o indexer em schedule, salvar um produto adiciona linhas ao changelog e o cron reindexa só o que mudou. Reindexações completas ficam raras. As contrapartidas estão em modos de indexer: save vs schedule.
• Tamanhos de batch. O Magento lê os dados dos produtos no MySQL e os envia ao OpenSearch em batches. Os tamanhos podem ser alterados no env.php, nas configurações de batch size do indexer. Batches maiores significam menos round trips, mas mais memória do PHP por batch. Mude só depois de medir.

'indexer' => [
    'batch_size' => [
        'catalogsearch_fulltext' => [
            'partial_reindex' => 100,
            'mysql_get' => 500,
            'elastic_save' => 500,
        ],
    ],
],

Para medir o tempo de um reindex completo em uma cópia de staging:

time bin/magento indexer:reindex catalogsearch_fulltext

Configurações do storefront que afetam a carga

Em Catalog Search no admin há opções que adicionam trabalho a cada request de busca. Search Suggestions e Search Recommendations rodam queries extras cada uma. Autocomplete Limit controla quantas sugestões a caixa de busca rápida devolve enquanto o cliente digita. Minimal Query Length evita buscas por um ou dois caracteres, que retornam quase o catálogo inteiro e são caras de agregar para a navegação em camadas.

A navegação em camadas é onde o OpenSearch trabalha mais nas páginas de categoria. Cada atributo filtrável vira uma aggregation. Ter cinquenta atributos filtráveis em uma categoria que usa só cinco ainda custa tempo de aggregation. Marque atributos como filtráveis só onde são usados.

Depurando problemas de busca

Produto sumido dos resultados

Siga em ordem. O produto está enabled, visível na busca, associado ao website e vendável, ou produtos sem estoque são exibidos? O indexer está valid e o changelog vazio? Depois confira o documento em si. Ache o índice por trás do alias e busque pelo SKU:

curl -s 'http://opensearch:9200/magento2_product_1/_search?pretty' \
  -H 'Content-Type: application/json' \
  -d '{"query": {"match": {"sku": "ABC-123"}}}'

O número depois de product_ é o ID da store. Se o documento não existe, o problema é de indexação. Se existe, o problema é a query, a relevância ou um filtro como visibilidade ou estoque.

Erros durante o reindex

• Conflitos de mapping. Geralmente um atributo cujo tipo mudou, ou um módulo customizado adicionando um campo com o tipo errado. Um reindex completo recria o índice com mappings novos.
• Campos demais. O OpenSearch limita o número de campos por índice. Lojas com muitos atributos e muitas store views podem chegar nesse limite. O conserto de verdade é reduzir atributos pesquisáveis e filtráveis.
• Timeouts. Aumente o timeout do servidor no Magento só depois de saber por que o cluster está lento. Na maioria das vezes é pressão de heap ou disco.

Ajuste de relevância, sinônimos e stopwords têm artigo próprio: sinônimos e relevância na busca.

Monitoramento

No mínimo, alerte quando a saúde do cluster não for green, quando o heap da JVM ficar acima de uns 85 por cento por um período sustentado e quando o disco passar do low watermark. Alerte também do lado do próprio Magento: indexers invalid, backlog do changelog crescendo e cron parado. A maioria das quedas de busca que investiguei começou com uma dessas coisas passando despercebida por dias.

FAQ

O Magento 2.4.8 roda sem OpenSearch ou Elasticsearch?

Não. Desde o 2.4.0 um motor de busca é obrigatório e a busca por MySQL foi removida. Listagem de catálogo, busca e navegação em camadas dependem dele. Alguns módulos de terceiros o substituem por outros motores, mas o core precisa de um.

Quanta memória o OpenSearch precisa para o Magento?

Depende do tamanho do catálogo e das store views. Alguns gigabytes de heap bastam para a maioria das lojas. Defina Xms e Xmx com o mesmo valor, em torno de metade da memória da máquina, e acompanhe o uso do heap durante um reindex completo.

Por que meu cluster OpenSearch está yellow?

Em um único nó, quase sempre são shards de réplica não alocados. Defina réplicas como zero para os índices do Magento com um index template. Em um cluster com vários nós, verifique a alocação com a API cluster allocation explain.

Preciso reindexar depois de mudar as configurações do OpenSearch no Magento?

Depois de mudar host ou porta, não, basta limpar o cache de config. Depois de mudar o index prefix ou o motor, rode um reindex completo do catalogsearch_fulltext para os índices existirem com os novos nomes.

Atendo como freelancer em Magento e Adobe Commerce, incluindo setup e performance de busca. Se precisar de ajuda com isso, fale comigo.