Pular para o conteúdo

Esta página é uma tradução automática da página em inglês, que é a versão de referência. Ler a página em inglês

Executando o servidor: iniciar, parar e verificações de saúde

Como iniciar e parar o servidor, obter a imagem dele e acompanhá-lo enquanto roda: métricas, traces, a fila de jobs e verificações de saúde.

Janela do terminal
my config check # report every configuration problem at once
my config check -instance # also warn about instance settings that are not set (opens the database)
my serve # start according to the configured role (-config <file> reads a TOML file)
my version # print the version of the binary

my serve valida a configuração, constrói os adaptadores de banco de dados, de fila de jobs e de gerenciamento de chaves, e aceita HTTP em listen. Com tls = off, o padrão, ele fala HTTP/1.1 simples ali: coloque na frente um proxy reverso ou balanceador de carga que termine o HTTPS (e HTTP/2 ou HTTP/3 para os clientes) e encaminhe por HTTP/1.1. Para servir HTTPS sem um proxy, veja Servindo HTTPS pelo servidor. As atualizações em tempo real (GET /api/v1/streaming, os streams das linhas do tempo local e federada e os streams das salas de chat de voz) são respostas de longa duração que enviam um comentário de heartbeat a cada 30 segundos (15 em uma sala de voz) e permanecem abertas enquanto ociosas. O proxy não deve armazenar essas respostas em buffer (nginx: o servidor envia X-Accel-Buffering: no), e o timeout de ociosidade ou de leitura dele precisa ser maior que o intervalo do heartbeat. Ele não aplica o esquema nem executa as etapas de atualização de dados: execute my schema apply e depois my db upgrade antes de iniciar (veja Banco de dados; as atualizações executam os dois como parte de Atualizando). Até my db upgrade ter registrado todas as etapas da versão, /readyz responde 503. Na configuração do Docker Compose (deploy/docker/compose.yaml; veja Implantando com Docker Compose), os serviços avulsos schema e upgrade executam my schema apply e my db upgrade antes de o servidor iniciar. Se o esquema não foi aplicado, o processo ainda inicia e a prontidão retorna 503, e ele não serve mais nada até o esquema existir.

O primeiro my serve ou comando my que usa o banco de dados grava host e account_domain nele. Quando a configuração difere dos valores gravados, my serve registra start failed com os dois pares de valores e termina com o código 1, e os comandos imprimem o mesmo erro. As exceções são my schema apply e my db backup, que não verificam, e o modo de manutenção, que não lê o banco de dados. my config check -instance e my db upgrade -check verificam, mas não gravam nada. Um processo que não pôde ler o banco de dados quando iniciou não está pronto até poder, e até lá ele não executa jobs e responde 503 com Retry-After a toda requisição, exceto as verificações de saúde (/healthz, /readyz, /health/live, /health/ready, /api/v1/instance/health). Isso também é o que acontece com um servidor iniciado antes de my schema apply. Se ele então encontrar valores diferentes, ele para com o mesmo erro.

No perfil production, my config check também verifica se as configurações válidas servem a uma instância de produção: erros, como um host que outros servidores não alcançam ou uma KEK que não é aleatória, fazem-no terminar com 1, e avisos, como mail = none, não. my serve registra os dois como avisos quando inicia, mas inicia mesmo assim, então execute my config check como uma etapa da implantação. A lista de verificação de produção lista as verificações e o que conferir à mão antes de entrar no ar.

role HTTP Worker de jobs
all (padrão) Todas as rotas Executa
web Todas as rotas Não executa
worker Apenas verificações de saúde (para sondas da plataforma) Executa

Os logs vão para a saída de erro padrão como JSON Lines. Toda linha tem level (DEBUG, INFO, WARN, ERROR) e severity, o mesmo nível na forma que o Cloud Logging lê (DEBUG, INFO, WARNING, ERROR e CRITICAL para um erro que para o processo). Os logs gravados ao tratar uma requisição trazem um request_id, e o mesmo ID é retornado no cabeçalho de resposta X-Request-Id. Se o X-Request-Id da requisição tem no máximo 128 caracteres de letras, dígitos e -_.:, ele é usado como está, como o ID atribuído por um balanceador de carga. Os logs dentro de um trace (requisições e jobs) também trazem trace_id e span_id (veja Traces).

Cada requisição HTTP e cada execução de job grava uma linha quando termina. A linha tem os mesmos nomes e valores dos rótulos das métricas abaixo, então no Cloud Run com metrics_exporter = none você pode criar métricas baseadas em logs do Cloud Logging (contadores e distribuições) a partir dessas linhas.

Linha (msg) Campos
http request (INFO; as verificações de saúde usam DEBUG) http.request.method, http.route, my.surface e http.response.status_code (um número) têm os mesmos valores dos rótulos de http.server.request.duration. Também duration_seconds (um número de segundos), url.path (o caminho sem a query string), http.response.body.size e request_id. http.route e my.surface ficam ausentes em requisições que não chegaram a uma rota (verificações de saúde, requisições recusadas antes do roteamento), e a métrica não as conta. Uma requisição cujo cliente saiu antes de o servidor poder responder tem o status 499 em vez de um 5xx, a menos que um handler tenha entrado em panic; o cliente não recebeu nada, então ela não conta como erro do servidor
job (INFO em caso de sucesso e para postponed, WARN para retry, ERROR para dead) my.job.type e my.outcome têm os mesmos valores dos rótulos de my.job.duration. Também duration_seconds (my.job.duration), wait_seconds (my.job.wait), job_id, attempt e error em caso de falha
error report (ERROR; CRITICAL para uma falha que para o processo) Uma linha por erro relatado (Relatórios de erros)

O guia Relatório de erros explica onde ler essas linhas em cada plataforma, a tela Erros, as notificações e o envio de relatórios a um rastreador de erros.

O servidor reporta os erros que precisam da atenção do operador como uma linha error report cada:

  • um pânico em um handler HTTP, um job ou uma tarefa em segundo plano;
  • um erro por trás de uma resposta 5xx da API de cliente, da API de administração, das páginas de login, do ActivityPub, do OAuth ou de mídia;
  • um job que falha de vez (dead): ele esgotou as tentativas ou se recusou a executar de novo. As entregas que desistiram porque o outro servidor continuou falhando não são reportadas;
  • uma falha ao iniciar: uma configuração inválida, ou um banco de dados ou adaptador que não pode ser configurado.

Respostas 4xx, novas tentativas de jobs, o modo de manutenção, verificações de prontidão com falha, requisições cujo cliente saiu e falhas causadas por outros servidores não são reportadas; as métricas e as demais linhas de log cobrem esses casos.

Quando o cliente de uma requisição vai embora, as outras linhas de erro do servidor para essa requisição são escritas em INFO em vez de ERROR, já que a maioria delas apenas diz que a requisição foi cancelada.

A linha está na forma que o Google Cloud Error Reporting lê: no Cloud Run, os relatórios aparecem no Error Reporting agrupados como erros, sem nenhuma configuração. Em outras plataformas, é uma linha JSON simples:

Campo Valor
@type, serviceContext O tipo de evento do Error Reporting, e {"service": "my", "version": "<version>"}
my.error.fingerprint 32 dígitos hexadecimais que são os mesmos para toda ocorrência do mesmo erro: montados a partir da origem, do local, do tipo do erro e das funções do servidor na pilha, sem números de linha
my.error.source, my.error.kind server (ou web), e panic ou error
my.error.where Onde aconteceu: <surface> <method> <route> para uma requisição (como client_api GET /api/v1/statuses/{id}), o tipo do job para um job, o nome da tarefa para uma tarefa em segundo plano, startup para uma falha ao iniciar
context.httpRequest Para um erro de uma requisição: method, url (a rota, como /api/v1/statuses/{id}, nunca o caminho que o cliente pediu) e responseStatusCode, o status respondido (500)
my.role, deployment.environment.name O role do processo e errors_environment
request_id, job_id, attempt, trace_id, span_id Os IDs para encontrar as linhas de requisição ou de job do mesmo erro, quando ele os tem
message Por último na linha: <type>: <message>, uma quebra de linha e a pilha do Go

Antes de um relatório sair do processo, a mensagem tem URLs, endereços de e-mail, handles @user@host, endereços IP, UUIDs e ULIDs e números de 10 dígitos ou mais substituídos por <url>, <email>, <acct>, <ip>, <id> e <n>, e é cortada em 1 KiB. A pilha mantém as posições de arquivo, mas não os valores dos argumentos das linhas de função (eles aparecem como (...)), e é cortada em 16 KiB. Nenhum relatório traz corpo de requisição, cabeçalho, query, cookie, conta, nome de usuário, endereço IP ou User-Agent. Nenhuma outra linha traz uma pilha; assim, o Error Reporting encontra apenas as pilhas dessas linhas.

O nome de um campo é uma única chave que contém .; ela não é aninhada. Coloque-o entre aspas nos filtros e extrações do Cloud Logging (por exemplo jsonPayload."http.route", e EXTRACT(jsonPayload.duration_seconds) para o valor de uma distribuição). Os campos usados como rótulos recebem valores de um conjunto finito apenas; url.path, request_id e job_id nunca são rótulos.

Com metrics_exporter = emf, essas duas linhas são as próprias linhas EMF. A linha http request traz o valor de http.server.request.duration, e a linha job traz os valores de my.job.duration e my.job.wait (chaves com o nome das métricas), além da diretiva _aws, service.name, service.version e my.role. Essas três métricas não são escritas em nenhuma outra linha. Os campos que você escolhe em metrics_emf_dimensions são escritos como strings, como o EMF exige (por exemplo, a dimensão http.response.status_code é "200"). Os logs vão para a saída de erro padrão e as demais linhas EMF vão para a saída padrão. O driver de log awslogs do ECS envia ambas ao CloudWatch Logs, de modo que as métricas são extraídas de ambas.

deploy/docker/ guarda o que implanta uma instância. compose.yaml executa sozinho, e os outros arquivos se sobrepõem a ele.

Arquivo Adiciona Use quando
compose.yaml O servidor e seus serviços avulsos de banco de dados, em SQLite e arquivos de mídia no volume data Sempre
compose.postgres.yaml PostgreSQL em um contêiner, no volume postgres Você quer PostgreSQL nesta máquina. Para um servidor PostgreSQL em outro lugar, deixe-o de fora e defina MY_DATABASE e MY_DATABASE_URL em .env
compose.s3.yaml Mídia em um bucket compatível com S3; com COMPOSE_PROFILES=garage também um armazenamento Garage de um nó no volume garage A mídia ultrapassa um disco, ou você a quer em um bucket. Sem o perfil, o armazenamento é o externo das configurações MY_BLOB_S3_*
compose.caddy.yaml Caddy, com certificados TLS nas portas 80 e 443 MY_HOST é um domínio público e nada mais termina o TLS nesta máquina
compose.build.yaml Constrói a imagem a partir de um checkout Você executa o seu próprio build

Escolha o banco de dados e o armazenamento de mídia antes da primeira inicialização: os dados não se movem sozinhos quando os arquivos mudam (Backup mostra o que precisa ser movido).

Sobreponha os arquivos com opções -f nessa ordem, ou nomeie-os uma vez em .env, para que todo comando docker compose posterior (exec, logs, pull e os dos outros guias) use os mesmos arquivos:

Janela do terminal
cd deploy/docker
cp example.env .env
# In .env: COMPOSE_FILE=compose.yaml:compose.postgres.yaml:compose.caddy.yaml

Um arquivo chamado compose.override.yaml no diretório é lido apenas quando nem -f nem COMPOSE_FILE nomeiam arquivos. Com eles, liste-o também.

Configurações. Copie example.env para .env. O Compose lê .env para preencher as variáveis dos seus arquivos e entrega o arquivo inteiro aos contêineres do servidor, então toda configuração da referência de configuração funciona sendo definida ali. O modelo lista todas, com uma frase sobre cada uma.

  • A chave de criptografia de chaves fica fora de .env, no arquivo secrets/kek, e os contêineres a leem como o segredo do Docker /run/secrets/my_kek, então ela nunca vira uma variável de ambiente. Uma linha MY_KEK em .env para o servidor, que recusa MY_KEK e MY_KEK_FILE juntos (gerenciando a chave).
  • O servidor executa como o usuário 65532, e o Compose monta o arquivo com as permissões que ele tem, então o arquivo precisa ser legível por outros. Guarde-o em um diretório em que só você entra, como fazem os comandos em example.env.
  • Os outros segredos chegam aos contêineres como variáveis de ambiente. Para passar um como arquivo no lugar, monte-o com um segredo em um compose.override.yaml seu e defina o <NAME>_FILE dele, como o compose.yaml faz para a chave.
  • .env guarda segredos: chmod 600 .env, e guarde uma cópia com os seus backups.
  • MY_LISTEN continua :8080, já que os arquivos se conectam a essa porta, a menos que o servidor sirva HTTPS por conta própria (Servindo HTTPS pelo servidor).

TLS com o Caddy. Defina MY_HOST como um domínio cujo DNS aponta para a máquina, com as portas 80 e 443 acessíveis pela internet, e remova MY_WEB_ORIGIN de .env. O Caddy obtém e renova o certificado por conta própria na primeira requisição. O servidor confia no X-Forwarded-For dos pools de endereços padrão do Docker; defina MY_TRUSTED_PROXIES se os seus forem diferentes.

O Garage incluído. compose.s3.yaml com COMPOSE_PROFILES=garage precisa dos valores que example.env lista no topo. O serviço avulso garage-init prepara o armazenamento a cada up. Ele fica dentro da rede do Compose, já que o servidor serve a mídia por conta própria. Um nó é um disco: faça backup do volume garage ou do bucket (Backup).

O my pode servir HTTPS por conta própria, para que uma máquina pequena execute o servidor inteiro como um binário com um domínio e as portas 80 e 443, sem um proxy reverso. Com tls = acme, ele obtém os certificados de uma autoridade certificadora ACME, como o Let’s Encrypt. Com tls = files, ele serve um certificado e uma chave que você fornece e mantém atualizados com outra ferramenta, como o certbot.

Janela do terminal
MY_TLS=acme
MY_TLS_ACME_AGREE_TERMS=true # you agree to the terms of service of the certificate authority
# MY_TLS_ACME_EMAIL=ops@social.example optional contact of the account
# MY_LISTEN=:443 the default with tls other than off
# MY_TLS_HTTP_LISTEN=:80 the default; empty opens no port 80
Janela do terminal
MY_TLS=files
MY_TLS_CERT_FILE=/etc/letsencrypt/live/social.example/fullchain.pem
MY_TLS_KEY_FILE=/etc/letsencrypt/live/social.example/privkey.pem
  • Portas. O servidor serve HTTPS em listen (:443 por padrão quando tls não é off). Em tls_http_listen (:80 por padrão) ele redireciona requisições GET e HEAD para o mesmo caminho em https com 301, e responde 400 a qualquer outro método, para que nenhum corpo de requisição trafegue em texto simples.
  • Hosts. O servidor serve host e o host de web_origin quando for diferente. Um handshake para qualquer outro nome falha sem um certificado, e nunca faz o servidor pedir um.
  • Conexões. TLS 1.2 ou posterior com as suítes de cifras padrão do Go, HTTP/2 e HTTP/1.1, no máximo 64 KiB de cabeçalhos de requisição e no máximo 100 streams simultâneos em uma conexão HTTP/2. Os timeouts são os do HTTP simples. O servidor ainda adiciona Strict-Transport-Security a toda resposta (Cabeçalhos de segurança).
  • Papéis. Apenas os papéis web e all escutam com TLS. Um worker serve as verificações de saúde em HTTP simples em listen (:8080 por padrão) e não abre a porta 80.
  • Endereços de cliente. Sem um proxy na frente, o par da conexão é o cliente: deixe trusted_proxies vazio. Defina-o apenas quando uma CDN na frente se conecta ao servidor por https.
  • Modo de manutenção. my serve -maintenance não lê nem tls nem os certificados e responde em HTTP simples em listen (:8080, a menos que você o defina), então aponte MY_LISTEN e o seu firewall para essa porta enquanto ele executa, ou mantenha um proxy reverso para a manutenção.

Com tls = acme, o servidor pede um certificado para cada um dos seus hosts que não tem um, à autoridade certificadora em tls_acme_directory (Let’s Encrypt por padrão).

  • Antes de começar. host precisa ser um nome DNS que aponta para o servidor, e as portas 443 e 80 precisam estar acessíveis pela internet: a autoridade certificadora verifica que o servidor controla o nome conectando-se a ele. Ela responde em listen (o desafio TLS-ALPN-01) ou em tls_http_listen (o desafio HTTP-01), então um tls_http_listen vazio ainda funciona só com a porta 443. Certificados curinga e validação por registros DNS não estão disponíveis.
  • Primeira inicialização. O servidor começa a escutar sem esperar um certificado e depois os pede. Até um host ter o certificado dele, um handshake para ele falha; com o Let’s Encrypt os primeiros certificados costumam chegar em um minuto. O log diz obtained a TLS certificate para cada host e the TLS certificate could not be obtained com o motivo quando um pedido falha.
  • Renovações. O servidor renova cada certificado no momento que a autoridade certificadora sugere para ele (ACME Renewal Information): ele escolhe uma vez um horário aleatório dentro da janela sugerida, o mantém enquanto a janela continua e pergunta de novo como o Retry-After da autoridade diz, ao menos a cada 12 horas, para que uma autoridade que precise substituir certificados antes possa mover a janela. Quando a autoridade não oferece essa janela, o servidor renova depois de dois terços da vida do certificado, ou depois da metade dela para um certificado válido por menos de 10 dias. Uma renovação informa à autoridade qual certificado ela substitui, o que a mantém fora dos limites de taxa do Let’s Encrypt. O certificado atual continua em serviço até a renovação chegar, e uma renovação que falha espera como um primeiro pedido.
  • Pedidos com falha. Depois de um pedido com falha, o servidor espera antes do próximo para o mesmo host: 1 minuto depois da primeira falha, 10 minutos depois da segunda, 100 minutos depois da terceira e depois um dia, para ficar dentro dos limites da autoridade certificadora. A espera é guardada no banco de dados e sobrevive a reinícios. Corrija a causa (DNS, um firewall, uma porta) e o próximo pedido sai quando a espera termina.
  • Onde eles são guardados. A conta com a autoridade certificadora, os certificados e o registro de cada pedido são guardados no banco de dados; as chaves privadas são seladas com a chave de criptografia de chaves, como os outros segredos (gerenciamento de chaves). Um backup do banco de dados os inclui, e um servidor reiniciado serve os certificados guardados na hora, sem pedir. Trocar a chave de criptografia de chaves os envolve de novo; isso não pede novos certificados.
  • Vários processos. Os processos que compartilham o banco de dados e o armazenamento kv se coordenam: um pede o certificado de um host enquanto os outros esperam e depois o carregam, e o processo a que a autoridade certificadora se conectar responde à verificação dela. Use kv = db ou kv = valkey; kv = memory é recusado, a menos que um processo execute tudo (role = all). O processo que obtém um certificado avisa os outros pelo broker de stream, e eles o servem em segundos; cada processo web com tls = acme portanto continua escutando no broker. Com stream = hub, ou quando um aviso se perde, todo processo ainda lê os certificados atuais do banco de dados a cada 5 minutos, e a cada minuto depois que o certificado dele chegou ao horário de renovação, então uma renovação chega a eles bem antes de o certificado antigo expirar.
  • Perfis. tls_acme_profile escolhe um perfil que a autoridade certificadora oferece, como shortlived no Let’s Encrypt. Vazio usa o padrão dela. Depois de uma mudança de perfil, a próxima renovação o segue, e o certificado que ela traz é servido mesmo quando expira antes do que ele substitui.

Para experimentar sem gastar os limites do ambiente de produção do Let’s Encrypt, comece pelo ambiente de staging dele, que emite certificados em que os navegadores não confiam, com limites muito mais altos:

Janela do terminal
MY_TLS_ACME_DIRECTORY=https://acme-staging-v02.api.letsencrypt.org/directory

Quando o log disser que os certificados foram obtidos e curl -kv https://social.example/ mostrar um certificado de (STAGING), remova a configuração e reinicie. O servidor registra uma nova conta no ambiente de produção e pede os certificados dele ali; os de staging ficam no banco de dados e deixam de ser servidos.

Com tls = files, tls_cert_file guarda primeiro o certificado do servidor e depois os intermediários dele (o fullchain.pem do certbot); tls_key_file guarda a chave dele. O certificado precisa cobrir host, e ele também serve o host de web_origin quando for diferente e o certificado o cobrir.

O servidor olha os horários de modificação dos dois arquivos a cada minuto e os carrega de novo quando qualquer um muda, sem reiniciar. Um par que ainda não corresponde (um certificado novo antes da chave nova) mantém o certificado anterior em serviço até a próxima verificação, e o log diz o motivo.

my tls mostra e controla os certificados com a configuração do servidor, a partir de qualquer máquina que alcance o banco de dados (a CLI de administração):

Janela do terminal
my tls status # each host: certificate, renewal, latest orders
my tls renew -host social.example # order now, without waiting
my tls revoke -host social.example -reason key_compromise
  • status mostra, para cada host, o certificado atual (o número de série, o emissor e a validade), quando ele é renovado (a janela da autoridade certificadora, ou o horário derivado da vida dele), quantos pedidos seguidos não obtiveram nenhum e os últimos pedidos com seus erros. Com tls = files ele mostra o certificado de tls_cert_file.
  • renew pede um certificado agora, ignorando o horário de renovação e a espera depois de pedidos com falha: execute-o depois de corrigir a causa dos pedidos com falha. O servidor em execução responde à verificação da autoridade certificadora, então ele precisa estar no ar, e os processos dele servem o novo certificado em segundos, ou em 5 minutos com stream = hub.
  • revoke primeiro pede um certificado que substitui o atual e depois pede à autoridade certificadora que revogue o atual e o registra; todo processo deixa de servir o certificado revogado em segundos, ou em 5 minutos com stream = hub. Use key_compromise quando a chave privada pode ser conhecida por outros, superseded ou operator caso contrário. Quando o substituto não pode ser pedido, a revogação segue em frente: os processos servem o certificado anterior do host se ele não foi revogado, ou nada até o servidor obter um novo.
  • renew e revoke exigem tls = acme e um kv diferente de memory, já que os processos a que a autoridade certificadora se conecta leem as respostas às verificações dela do armazenamento kv. Com tls = files eles são recusados: renove ou revogue o certificado com a ferramenta que grava os arquivos.

Com metrics_exporter definido, crie alertas para my.tls.certificate.expiry abaixo de 7 dias e para my.tls.order.consecutive_failures de 3 ou mais (alertas): uma renovação com falha aparece semanas antes de o certificado expirar.

Com tls = acme, my config check relata como erros termos com os quais não se concordou, um host que é um endereço IP, localhost ou um nome sem ponto, um tls_acme_directory que não é uma URL https e kv = memory com um role diferente de all. Com tls = files, ele relata como erros um certificado ou uma chave que não pode ser lido, uma chave que não corresponde ao certificado e um certificado que não cobre host, expirou ou ainda não é válido, e avisa quando restam menos de 14 dias. Ele avisa quando trusted_proxies está definido com tls diferente de off. Com tls = off ele avisa quando listen é a porta 80 ou 443 em um endereço diferente de loopback, já que nada parece terminar o TLS na frente do servidor; o servidor registra o mesmo aviso uma vez por inicialização quando um servidor assim, com trusted_proxies vazio, recebe uma requisição HTTP simples de um endereço diferente de loopback.

systemd. Portas abaixo de 1024 exigem uma capability para um usuário diferente de root. Dê-a ao serviço e a mais nada:

[Service]
User=my
AmbientCapabilities=CAP_NET_BIND_SERVICE
CapabilityBoundingSet=CAP_NET_BIND_SERVICE

Com tls = files, o usuário também precisa ler os arquivos de certificado. Com o certbot, os diretórios live e archive dele são legíveis apenas pelo root: dê ao grupo do serviço acesso (chgrp e chmod g+rx nos diretórios, g+r nas chaves), ou copie os arquivos em um deploy hook para um diretório que o serviço leia.

Docker. O Docker 20.10 e posteriores deixam um contêiner abrir portas abaixo de 1024 sem uma capability, então a imagem funciona como está. A imagem define MY_LISTEN=:8080, então defina MY_LISTEN=:443 em .env e publique as duas portas em um compose.override.yaml (ports: ["80:80", "443:443"]). Com tls = files, monte os arquivos de certificado somente para leitura onde MY_TLS_CERT_FILE e MY_TLS_KEY_FILE apontam; o servidor executa como o usuário 65532, que precisa poder lê-los. Com tls = acme não há nada a montar: os certificados ficam no banco de dados. Deixe de fora compose.caddy.yaml, que tomaria as mesmas portas. Isso não vale com network_mode: host, em que o contêiner compartilha a rede da máquina e precisa da mesma capability que um serviço fora de um contêiner.

Em comparação com o Caddy. Servir HTTPS pelo my abre mão do HTTP/3, da compressão das respostas (o servidor envia os arquivos do cliente web comprimidos e não comprime mais nada), de um log de acesso próprio (as linhas de log http request do servidor continuam) e de certificados validados por DNS, inclusive certificados curinga. Mantenha compose.caddy.yaml, ou outro proxy, quando precisar de qualquer um destes.

A imagem do servidor é ghcr.io/mycroblog/my, pública, para linux/amd64 e linux/arm64, com todos os adaptadores.

Tag Aponta para Use para
0.1.0 Essa versão, para sempre Nomear uma versão
0.1 O patch mais recente da v0.1 Docker Compose, que aplica o schema a cada up
0.1.0-rc.1 Essa pré-versão Testar uma versão antes de ela sair
nightly O commit mais recente de main que passou nos testes noturnos, movido a cada noite em que muda Experimentar mudanças antes de uma pré-versão, em uma instância que você possa descartar

Não há latest nem 0: ambos atravessariam uma versão menor, e cada atualização para uma nova versão menor precisa passar pela anterior. Nomeie uma versão em todo comando; docker pull ghcr.io/mycroblog/my sozinho falha com manifest unknown. Uma versão de patch também pode precisar de my schema apply e my db upgrade; portanto, fora do Docker Compose, siga Atualizando para cada versão. Em produção, fixe o digest que as notas da versão informam:

ghcr.io/mycroblog/my:0.1.0@sha256:...

nightly não tem caminho de atualização. As atualizações são prometidas apenas entre versões publicadas: de uma imagem nightly para a seguinte, ou de nightly para uma versão, o schema e os passos de dados de my db upgrade podem mudar de formas pelas quais nenhuma versão passa, então espere recriar o banco de dados dela. Nunca a execute em produção. my version exibe qual commit ela é, como em v0.1.0-rc.5.0.20261109182600.g7a789720a1b2: uma versão posterior à última versão publicada (v0.1.0-rc.5), o horário do commit em UTC e os 12 primeiros caracteres do commit depois de g. Para manter uma compilação, fixe o digest dela (ghcr.io/mycroblog/my:nightly@sha256:...): uma compilação mais antiga perde a tag, mas continua disponível para pull pelo digest.

Onde executá-la:

  • Docker Compose: deploy/docker/compose.yaml executa a imagem de MY_VERSION em .env (Arquivos do Docker Compose). Para compilá-la a partir de um checkout, adicione a sobreposição compose.build.yaml (docker compose -f compose.yaml -f compose.build.yaml up -d --build) e defina MY_VERSION com um nome seu, pois ele nomeia a sua imagem local e é o que my version exibe.
  • Kubernetes: baixe-a do ghcr.io como está.
  • Cloud Run: use a imagem do ghcr.io diretamente. Uma implantação resolve a tag para um digest.
  • AWS (ECS, EKS): copie a imagem para o Amazon ECR, ou use um pull through cache do ECR, que precisa de credenciais do ghcr.io.

Cada imagem publicada tem uma proveniência assinada pelo Sigstore, que liga o digest ao workflow e ao commit que a compilaram, e um SBOM. Com a GitHub CLI, e com login no ghcr.io se o comando pedir:

Janela do terminal
gh attestation verify oci://ghcr.io/mycroblog/my@sha256:... -R mycroblog/my \
--signer-workflow mycroblog/my/.github/workflows/release.yml
docker buildx imagetools inspect ghcr.io/mycroblog/my@sha256:... --format '{{ json .SBOM }}'

O primeiro comando falha, a menos que a imagem tenha sido compilada pelo workflow de release deste repositório. Para uma imagem nightly, verifique-a com --signer-workflow mycroblog/my/.github/workflows/nightly.yml. Ele exibe o commit, que é o commit da tag da versão; o rótulo org.opencontainers.image.revision da imagem nomeia o mesmo.

my é licenciado sob a AGPL-3.0-only. A seção 13 da AGPL-3.0 exige que quem executa o servidor e permite que usuários interajam com ele por uma rede ofereça a esses usuários uma forma de obter o código-fonte correspondente do programa em execução. Isso vale para todos que interagem com o servidor, não apenas para quem tem uma conta.

Indique onde o código-fonte é publicado com a configuração source_url (variável de ambiente MY_SOURCE_URL; veja a referência de configuração).

Valor Significado
Não definido O padrão, https://github.com/mycroblog/my. Use-o quando executar o my sem modificações: o GET /instance de uma versão então nomeia o código-fonte dessa versão, https://github.com/mycroblog/my/tree/v0.1.0, e o NodeInfo o repositório
Uma URL https: Um lugar onde o código-fonte pode ser lido (o repositório de um fork, a tag ou o arquivo de uma versão específica, e assim por diante)
Um URI mailto: Um endereço de e-mail para pedir o código-fonte (por exemplo mailto:source@example.org; ?subject=... é permitido)

Qualquer outro valor (http:, git@..., um caminho relativo, uma URL com informações de usuário ou um #, um mailto: sem endereço, e assim por diante) faz my config check falhar, e o servidor não inicia.

O valor aparece nestes lugares:

  • source_url no GET /instance da API de cliente
  • A seção “Código-fonte” da página de informações da instância do cliente web (/about) e um link na página de apresentação (/)
  • metadata.sourceCode no NodeInfo (/nodeinfo/2.1). Uma URL https: também é publicada como software.repository (o schema do NodeInfo 2.1 permite apenas uma URL http(s) em software.repository, de modo que um valor mailto: aparece somente em metadata.sourceCode)

Se você executa um my modificado (aplica patches, compila um fork ou troca dependências), a URL padrão deixa de apontar para o código-fonte do que está em execução. Altere source_url para onde o código-fonte da versão em execução, com as suas modificações, pode ser encontrado. Apontar para o commit, a tag ou o arquivo que corresponde à versão em execução, em vez do estado mais recente de um repositório, permite que os usuários obtenham o mesmo código-fonte de forma confiável. Se você executa uma versão oficial sem modificações, mantenha o padrão.

  • Esteja pronto para entregar o código-fonte correspondente (incluindo os scripts necessários para compilá-lo) prontamente quando alguém pedir. Apenas nomear um endereço, sem estar preparado para entregar, não cumpre a obrigação.
  • Use um endereço que continue funcionando depois que você parar de operar o servidor ou que a pessoa responsável mudar. Um endereço compartilhado de operações é melhor que uma caixa de entrada pessoal.
  • Garanta que o filtro de spam não descarte os pedidos.
  • Use um endereço que você aceite tornar público: qualquer pessoa pode vê-lo na página de informações, na página de apresentação e no NodeInfo.

A configuração metrics_exporter (padrão none) exporta as métricas do serviço. As configurações relacionadas a ela estão na referência de configuração.

metrics_exporter Caminho Indicado para
none Nada é exportado. A instrumentação custa quase nada. Os valores da instância inteira ainda vão para uma linha de log metrics snapshot a cada 15 minutos Cloud Run (use no lugar as métricas da plataforma e as métricas baseadas em logs)
prometheus GET /metrics em metrics_listen (padrão 127.0.0.1:9464). É um listener separado do listen público, sem autenticação, e executa para todo role Auto-hospedado (coletado por um servidor compatível com Prometheus ou pelo KEDA)
otlp Enviado a um OpenTelemetry Collector por OTLP/HTTP. O destino vem das variáveis de ambiente padrão do OTel, como OTEL_EXPORTER_OTLP_ENDPOINT Configurações em que você pode executar um coletor
emf Linhas JSON no CloudWatch Embedded Metric Format. As métricas de requisições e de jobs vão nas linhas de log de encerramento acima; as outras são gravadas na saída padrão, uma linha por conjunto de rótulos, quando uma requisição ou um job termina AWS ECS

As métricas estão listadas abaixo. No Prometheus, . em um nome vira _ e um sufixo de unidade (_seconds, e _total para um contador) é adicionado.

Métrica Tipo Rótulos
http.server.request.duration Histograma, segundos http.request.method, http.route (o caminho do padrão da rota; other quando nenhum corresponde), http.response.status_code, my.surface (client_api / admin / activitypub / oauth / media / web / payments / voice / queue)
http.server.active_requests UpDownCounter my.surface
my.inbox.activities Contador activity.type (um tipo de Activity conhecido, ou other), my.outcome (accepted / duplicate / rejected / ignored / error), my.inbox.rejection (apenas com rejected: signature para uma assinatura ou prova de integridade ausente, inválida ou que não verifica, ou cuja chave não pôde ser buscada; suspended para um domínio suspenso; federation_off; rate_limited; invalid para uma atividade sem id, type, actor ou object válido)
my.relay.activities Contador my.outcome (admitted / over_limit / restricted / not_receiving: se uma atividade trazida por um relay foi ingerida, e por que foi descartada; veja Relays de federação)
my.move.activities Contador my.outcome (recorded / duplicate / not_own_actor / same_account / target_unavailable / alias_missing / target_moved / suspended / too_soon: se um Move recebido foi registrado, e por que foi descartado)
my.delivery.attempts Contador my.outcome (success / retry / gone / failed; gone cobre um 410 e as entregas ignoradas porque o servidor está indisponível ou suspenso)
my.delivery.duration Histograma, segundos my.outcome
my.ux.duration Histograma, segundos my.ux.metric (lcp / inp / long_frame / transition / press / call_rtt / call_jitter), my.ux.name (a rota, o tipo de interação, a ação ou o transporte da chamada; medições de UX)
my.ux.call.packet_loss Histograma, porcentagem my.ux.name (o transporte da chamada)
my.plugin.failures Contador my.plugin.kind (um tipo de plugin), my.plugin.code (o código Connect da falha)
my.plugin.slot_wait Histograma, segundos my.plugin.kind (quanto tempo uma chamada esperou a vez entre as chamadas desse tipo que executam ao mesmo tempo)
my.hook.decisions Contador hook, mode, outcome (as decisões que um gancho de decisão registrou)
my.hook.failures Contador hook, outcome (timeout, error, invalid ou breaker_open)
my.hook.duration Histograma hook (segundos por chamada do plugin)
my.job.duration Histograma, segundos my.job.type (um tipo de job registrado, ou other), my.outcome (success / retry / dead / postponed: postponed é uma execução que não fez trabalho e não usa nenhuma das tentativas do job, como a busca de um cartão de link que espera pelo host dele)
my.job.wait Histograma, segundos my.job.type
my.link_card.host_pauses Contador http.response.status_code (429 / 503). Um por pausa das buscas de cartões de link de um host; veja Pré-visualizações de links
my.translation.requests Contador my.outcome (author / cache / provider / no_provider / limit / unsupported / failed). Um por pedido para traduzir uma publicação que o visitante pode ver, ou uma publicação ou um comentário de denúncia que um moderador pede: respondido com as próprias palavras do autor, com uma tradução guardada ou por um provedor, ou recusado porque nenhum provedor pode receber a publicação, um limite mensal foi atingido, nenhum provedor traduz o idioma ou nenhum provedor devolveu uma tradução utilizável.
my.translation.lock_waits Contador Nenhum. Um por pedido que esperou outro pedido traduzindo a mesma publicação para o mesmo idioma, em vez de perguntar a um provedor
my.translation.characters Contador my.provider (o ID de um provedor de tradução). Os caracteres de publicações e de comentários de denúncia enviados ao provedor, sem marcadores, inclusive chamadas que falham. É o que os limites mensais contam, e pode diferir do que o provedor cobra
my.timeline.delivery.lag Histograma, segundos Nenhum (da criação de uma publicação local até a gravação dela nas linhas do tempo iniciais e a notificação aos streams)
my.stream.connections UpDownCounter my.stream.kind (user, timeline para os streams das linhas do tempo local e federada, voice para os streams das salas de chat de voz)
my.stream.signals Contador my.stream.kind (user / timeline). Um por sinal que um stream aberto tratou, tenha ou não enviado algo ao cliente
my.accounts.registered Contador Nenhum
my.statuses.created Contador my.visibility
my.billing.imports Contador my.billing.source (aws / gcp / plugin), my.outcome (success / failed), error.type (apenas com failed: o tipo de falha, como em Importando custos de uso da nuvem). Toda tentativa conta, inclusive as novas tentativas e as falhas que esperam a próxima importação diária
my.supporter.tip_checkouts Contador my.outcome (started / rate_limited / paid / expired). Um por início de uma gorjeta que recebeu a página do provedor, por início que os limites recusaram e por gorjeta que foi paga ou terminou sem pagamento; veja gorjetas para os alertas a que ela serve
my.voice.turn.credentials Contador my.voice.turn (coturn / cloudflare), my.outcome (issued / reused / failed). Um por credencial TURN que um participante de chat de voz pediu ao entrar em uma sala ou renovar a conexão: reused significa que as credenciais da Cloudflare emitidas antes para a mesma conexão foram devolvidas de novo, e failed significa que a Cloudflare não pôde ser alcançada ou recusou, então o participante recebeu um erro e não pôde se conectar
my.errors.exported Contador my.outcome (success / dropped / failed: um por relatório de erro para o serviço de errors_exporter. dropped significa que o relatório não foi enviado porque 1.000 relatórios já estavam esperando ou o serviço pediu ao servidor que desacelerasse, e o servidor espera o tempo que o serviço pede antes de enviar de novo; failed significa que o serviço não pôde ser alcançado ou recusou o relatório. Um relatório é enviado uma vez e nunca repetido, e os relatórios que ainda esperam 2 segundos depois do início de um desligamento são perdidos)
my.queue.ready Medidor my.job.type (o número de jobs executáveis na fila do banco de dados)
my.queue.oldest_ready_age Medidor, segundos my.job.type (quanto tempo o job executável mais antigo de cada tipo na fila do banco de dados esperou; um tipo sem job executável não tem valor)
my.queue.dead Medidor Nenhum
my.instance.users, my.instance.statuses Medidor Nenhum (as contagens de usuários locais e de publicações, como no NodeInfo)
my.media.stored_bytes Medidor, bytes my.media.origin (local / remote_cache)
my.db.size Medidor, bytes Nenhum (o tamanho do banco de dados: pg_database_size para PostgreSQL; o arquivo do banco de dados sem o write-ahead log para SQLite)
my.billing.import.failing Medidor my.billing.source (1 quando a importação mais recente da fonte falhou, 0 caso contrário)
my.federation.instances Medidor my.federation.instance.state (available: servidores a que as entregas ainda vão, mas que falharam em pelo menos um dia desde a última vez que responderam; unavailable: servidores cujas entregas estão pausadas)
my.metrics.snapshot.age Medidor, segundos my.metrics.snapshot.part (queue / totals)
my.errors.reported Contador my.error.source (server / web), my.error.kind (panic / error). Um por relatório de erro
my.tls.certificate.expiry Medidor, segundos host (o tempo até a expiração do certificado que este processo serve para um dos seus hosts, com tls = acme ou tls = files; cada processo informa o seu, então um processo que ficou com um certificado antigo aparece. Veja Comandos e métricas)
my.tls.order.attempts Contador host, result (issued / failed). Um por pedido de um certificado à autoridade certificadora ACME, pelo processo que o fez, my tls renew e my tls revoke inclusive
my.tls.order.consecutive_failures Medidor host (os pedidos desde o certificado atual do host que não obtiveram nenhum: a contagem que define a espera antes do próximo pedido)
my.tls.rounds Contador Nenhum. Um por rodada do gerenciador de certificados sobre os hosts dele com tls = acme; uma contagem que para de crescer significa que o gerenciador parou

As verificações de saúde (/healthz, /readyz, /health/live, /health/ready) não são medidas. Nenhum rótulo contém um domínio remoto, uma conta, uma URL nem um IP de cliente. my.queue.*, my.instance.*, my.media.stored_bytes, my.db.size, my.federation.instances e my.billing.import.failing são valores da instância inteira: todo processo informa o mesmo valor a partir de um snapshot guardado no armazenamento chave-valor.

As métricas sobre o processo, o runtime do Go e as conexões com recursos são exportadas pelo mesmo metrics_exporter. A CPU do contêiner, a memória, o número de instâncias e as requisições de entrada ficam com as métricas da plataforma; estas cobrem a saturação dentro do processo que a plataforma não vê. Não as use para disparar o escalonamento; use-as para alertas e para estimar o limite de instâncias.

Métrica Tipo Rótulos
go.memory.used, go.memory.limit, go.memory.gc.goal Medidor, bytes Apenas go.memory.used tem go.memory.type (stack / other). go.memory.limit aparece apenas quando GOMEMLIMIT está definido
go.memory.allocated, go.memory.allocations Contador Nenhum
go.goroutine.count, go.processor.limit, go.config.gogc Medidor Nenhum
go.schedule.duration, go.memory.gc.pause.duration Histograma, segundos Nenhum (a espera de se tornar executável até executar, e as pausas do GC)
go.memory.gc.cycles Contador Nenhum
process.cpu.time Observable Counter, segundos (total desde o início) cpu.mode (user / system)
process.memory.usage Medidor, bytes Nenhum (memória residente, RSS)
process.unix.file_descriptor.count, my.process.file_descriptor.limit Medidor Nenhum (descritores de arquivo abertos e o limite)
process.uptime Medidor, segundos Nenhum
db.client.connection.count Medidor db.client.connection.pool.name (postgres / sqlite), db.client.connection.state (idle / used)
db.client.connection.max Medidor db.client.connection.pool.name
db.client.connection.wait_time, my.db.client.connection.waits, db.client.connection.timeouts Observable Counter (total desde o início; segundos ou contagem) db.client.connection.pool.name. timeouts é apenas do PostgreSQL
my.adapter.operation.duration Histograma, segundos my.adapter (queue.db / kv.db / kv.memory / kv.valkey / stream.<stream> / blob.fs), my.operation, my.outcome (success / error)
my.adapter.connections UpDownCounter my.adapter (conexões valkey e assinantes de stream.<stream>)
my.adapter.reconnects Contador my.adapter
http.client.request.duration Histograma, segundos my.http.purpose (json / html / image / video / human_check / web_push / webhook / client_metadata / login_provider / robots / domain_list), http.request.method, my.http.status_class (2xx e assim por diante), error.type (forbidden_destination é uma recusa da proteção contra SSRF)
http.client.open_connections UpDownCounter Nenhum
my.readiness.failures Contador Nenhum
my.readiness.shared Contador Nenhum. Um por requisição de prontidão que tomou o resultado de uma verificação já em execução em vez de iniciar uma
my.http.origin_refused Contador Nenhum. Um por requisição recusada porque não veio pela CDN (origin_secret). Sondagens do endereço da origem o aumentam devagar; um salto enquanto o tráfego para significa que a CDN deixou de enviar o cabeçalho. O modo de manutenção não mede nada, então apenas o log de acesso dele as mostra
  • As métricas do runtime do Go (go.*) são exportadas apenas por prometheus e otlp. Com emf, um job periódico de snapshot grava os medidores do processo e do pool de conexões e os contadores observáveis.
  • As esperas do pool e o tempo de CPU são Observable Counters: o pool e o kernel guardam totais desde o início, e eles são lidos no momento da coleta. No Prometheus são contadores _total (como process_cpu_time_seconds_total), no OTLP são somas monotônicas, e você vê o crescimento deles com o rate() do PromQL. O emf não tem contadores totais, então grava o aumento desde a gravação anterior (some-os com a estatística Sum do CloudWatch).
  • O claim da fila só é medido quando pega um job ou falha. O polling de um worker em espera não registra nada.
  • db.client.connection.pending_requests não é exportada: as estatísticas do pgx e do database/sql não informam quantas estão esperando, então o número e a duração das esperas a substituem.
  • Crie alertas para a razão da soma de go.memory.used para go.memory.limit e para o crescimento de db.client.connection.wait_time (o limite do pool está sendo atingido).

GOMEMLIMIT é uma variável de ambiente do runtime do Go que o operador define; a aplicação não a escolhe. Sem ela, o Go roda com o padrão (sem limite), e o heap não é coletado com antecedência ao se aproximar do limite de memória do contêiner. Em configurações com limite de memória do contêiner (Cloud Run, ECS, Kubernetes), defina-a para cerca de 90% desse limite (por exemplo GOMEMLIMIT=460MiB para um contêiner de 512 MiB). Não defina GOMAXPROCS: o padrão do Go acompanha o limite de CPU do contêiner.

A configuração traces_exporter (padrão none) exporta traces distribuídos. As configurações relacionadas estão na referência de configuração.

Span Nome Atributos
Requisição HTTP (servidor) <method> <http.route> (<method> para uma requisição que não chegou a uma rota) http.request.method, http.route, http.response.status_code, my.surface. Um 5xx é uma falha
Execução de job (consumidor) O tipo do job (my.job.type) my.job.type, my.job.attempt, my.outcome. Cada nova tentativa é um span separado
Transação my.db.transaction db.system.name. Cada nova tentativa é um span separado
Query (cliente) O nome da query do sqlc (como InsertJobs; caso contrário, a primeira palavra do SQL, como BEGIN) db.system.name, db.operation.name
Entrega (my.delivery) my.delivery activity.type, my.outcome
HTTP de saída (cliente) <method> http.request.method, server.address (somente o nome do host de destino), http.response.status_code. Um 4xx ou 5xx é uma falha

Um span com falha tem error.type (um nome finito como timeout, ou um código de status). Os atributos nunca contêm IDs de conta, publicação ou job, URLs, caminhos ou queries, IPs de cliente, valores de User-Agent, texto SQL ou strings de erro. server.address deixa os nomes de host dos servidores remotos com o receptor, de modo que você decide por quanto tempo o receptor os guarda e quem pode vê-los. As verificações de saúde e as requisições recusadas por origin_secret não criam span.

  • Uma execução de job não é filha do span que a enfileirou (em geral uma requisição HTTP). Ela é a raiz de um novo trace com um link para o span que a enfileirou. Em um visualizador, siga o link a partir do trace da requisição.
  • Um traceparent recebido só se torna o pai quando o par conectado está em trusted_proxies e, com origin_secret, a requisição traz o segredo. Caso contrário, é descartado e um novo trace começa. O tracestate é sempre descartado. O HTTP de saída (federação, WebFinger, mídia, Web Push e assim por diante) não carrega traceparent.
  • Amostragem: uma requisição é registrada se o pai dela, vindo de um proxy confiável, foi registrado, ou se o alvo do link de um job foi registrado; caso contrário, é registrada na proporção traces_sample_ratio (padrão 0,01). Reduzir a proporção nunca deixa sem trace os jobs que continuam uma requisição registrada.
Destino Configurações Caminho
Padrão, auto-hospedagem pequena traces_exporter = none Nenhum span é exportado. Siga request_id e job_id nos logs. Se um proxy confiável fornecer um traceparent, o trace_id e o span_id dele são adicionados aos logs
Auto-hospedagem (Jaeger, Tempo, um OpenTelemetry Collector e assim por diante) traces_exporter = otlp, traces_flush = batch Enviado por OTLP/HTTP ao receptor em OTEL_EXPORTER_OTLP_TRACES_ENDPOINT (ou OTEL_EXPORTER_OTLP_ENDPOINT, padrão http://localhost:4318). Os cabeçalhos de autenticação vão em OTEL_EXPORTER_OTLP_HEADERS. Para manter com segurança os erros e os traces lentos, use a amostragem tail do Collector
Google Cloud (Cloud Run) none, ou otlp com unit para ativar os traces Veja abaixo
AWS (ECS) none, ou otlp com batch para ativar os traces Veja abaixo

Mesmo com none, o trace de requisição que o Cloud Run cria automaticamente e o trace_id nos logs compartilham o mesmo ID (quando você confia, com trusted_proxies, na conexão que vem da frente do Cloud Run). Ainda não foi verificado se o Cloud Run sempre sobrescreve o traceparent das requisições públicas. Os logs não têm o formato do campo de trace que o Cloud Logging reconhece (logging.googleapis.com/trace).

Para enviar spans da aplicação ao Cloud Trace, execute um OpenTelemetry Collector como sidecar no mesmo serviço. O servidor não guarda credenciais do Google; o sidecar envia ao endpoint OTLP do Cloud Trace com as Application Default Credentials.

  • Servidor (o contêiner de entrada): MY_TRACES_EXPORTER=otlp, MY_TRACES_FLUSH=unit, OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
  • Sidecar: um OpenTelemetry Collector que recebe com um receptor otlp por HTTP em localhost:4318 e envia com o exporter googlecloud, ou o exporter otlphttp (https://telemetry.googleapis.com, com a extensão googleclientauth). Conceda à conta de serviço permissão para escrever no Cloud Trace.
  • Ao fim de cada requisição ou job registrado, unit descarrega os spans até ali para o sidecar antes de retornar. Para que o sidecar possa enviá-los enquanto nenhuma CPU está alocada, use cobrança baseada em instância em uma configuração com traces ativados.
  • O custo são os recursos do sidecar e o volume de spans (preços do Cloud Trace). Escolha a proporção com traces_sample_ratio.

Para enviar ao X-Ray, execute o AWS Distro for OpenTelemetry (ADOT) Collector como um contêiner sidecar em cada tarefa. O servidor não tem assinatura SigV4; o Collector assina com a função da tarefa e envia ao X-Ray. O módulo mycroblog-aws da implantação com OpenTofu faz tudo isso por padrão (observability.traces = "x-ray"); o restante desta seção é para uma definição de tarefa sua.

  • Servidor: MY_TRACES_EXPORTER=otlp, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://127.0.0.1:4318/v1/traces e o padrão MY_TRACES_FLUSH=batch, já que o processo continua no ar.
  • Collector: uma imagem fixada por versão, como public.ecr.aws/aws-observability/aws-otel-collector:v0.50.0, com a configuração dele na variável AOT_CONFIG_CONTENT: um receptor otlp por HTTP em 127.0.0.1:4318 e o exportador awsxray. O endpoint OTLP do X-Ray (https://xray.<region>.amazonaws.com/v1/traces, por um exportador otlphttp com a extensão sigv4auth) também funciona, mas exige o CloudWatch Transaction Search ativado na conta.
  • Conceda à função da tarefa xray:PutTraceSegments, com que o exportador awsxray grava. O servidor faz a amostragem dos traces por conta própria, então o Collector não precisa de regras de amostragem do X-Ray.
  • Dê ao Collector uma parte da tarefa: o mycroblog-aws dá a ele 32 unidades de CPU e 128 MiB, e ao servidor o restante, com GOMEMLIMIT em 90% desse restante. Faça o contêiner do servidor depender do início do contêiner do Collector, para que o Collector pare depois do servidor e receba os últimos spans.
  • O custo é a parte do sidecar nos recursos da tarefa e o número de traces que o X-Ray registra (os primeiros 100.000 por mês são grátis). O traces_sample_ratio padrão de 0,01 registra cerca de 30.000 traces por mês para 100.000 requisições por dia.

As métricas do sistema dizem quanta memória e CPU um processo usa; um profile do runtime do Go diz o que as usa. pprof_listen nomeia o endereço de um listener que serve os profiles em /debug/pprof/, para todo role. Ele vem vazio por padrão, o que não abre nenhum listener.

Janela do terminal
MY_PPROF_LISTEN=127.0.0.1:6060 my serve
go tool pprof -sample_index=inuse_space http://127.0.0.1:6060/debug/pprof/heap # what holds the heap now
go tool pprof -sample_index=alloc_space http://127.0.0.1:6060/debug/pprof/heap # what has allocated since the start
go tool pprof 'http://127.0.0.1:6060/debug/pprof/profile?seconds=30' # where the CPU goes, for 30 seconds
curl 'http://127.0.0.1:6060/debug/pprof/goroutine?debug=1' # every goroutine, by where it waits
curl 'http://127.0.0.1:6060/debug/pprof/heap?debug=1' | grep '^# ' # the runtime's memory statistics

O listener não tem autenticação, um profile mostra os detalhes internos do processo, e tirar um custa CPU: mantenha-o no loopback e chegue a ele por um túnel (ssh -L 6060:127.0.0.1:6060 <host>, kubectl port-forward), e remova a configuração quando terminar. O profile do heap cobre apenas o heap do Go. A memória residente do processo também guarda as páginas do binário que foram lidas, as pilhas e as estruturas do próprio runtime; as estatísticas de memória mostram essas. Os profiles de mutex e de block estão vazios: o servidor não os amostra.

Ao receber SIGTERM ou SIGINT, o servidor desliga de forma ordenada.

  1. Ele para de aceitar novas conexões e de pegar jobs.
  2. Espera até 25 segundos para as requisições em andamento e os jobs em execução terminarem.
  3. Após 25 segundos, cancela o contexto das requisições e jobs restantes e fecha as conexões. Em seguida, dá a um job cancelado até mais 3 segundos para registrar o resultado e termina com código 1 (no máximo 28 segundos no total, dentro do período de tolerância padrão de 30 segundos do Kubernetes e do ECS). Um job cancelado é repetido. Um job que não para nesses 3 segundos, ou que é encerrado no meio, é abandonado e retomado por um worker quando o lease dele expira; portanto, pode executar duas vezes.

Um pânico em uma das tarefas em segundo plano do servidor inicia o mesmo desligamento, para que o servidor nunca continue rodando em um estado quebrado. A linha de log serve failed nomeia a tarefa, e o processo termina com código 1 para que a plataforma ou o gerenciador de processos o reinicie.

Para trabalhos no banco de dados, no armazenamento chave-valor ou na fila, reinicie em modo de manutenção (MY_MAINTENANCE=true) em vez de parar. Veja Manutenção.

Jobs lista todos os tipos de job: o que ele faz, o que o inicia, como ele tenta de novo e o que executá-lo de novo faz.

A página de jobs da administração (Administração → Jobs, /admin/jobs, permissão manage_jobs) tem três páginas:

  • Estado da fila (/admin/jobs): quantos jobs falharam, primeiro, com um link para eles; a contagem por estado (na fila, em execução, aguardando nova tentativa, com falha), cada uma levando aos jobs nesse estado; quanto tempo o job vencido mais antigo esperou; e uma tabela das contagens por tipo e estado com quanto tempo cada tipo mantém um job esperando.
  • Lista de jobs (/admin/jobs/list): os jobs que não terminaram (na fila, em execução, aguardando nova tentativa), ou de um estado, e de um tipo, uma página por vez, com o tipo, o número de tentativas, o horário em que vence ou falhou, o estado e a primeira linha do último erro.
  • Um job (/admin/jobs/<id>, a partir do tipo na lista): Executar de novo para um job com falha, que pede confirmação antes, já que uma execução pode repetir o que o job fez antes de falhar; todos os dados do job, o ID e as chaves dele, cada um com um botão de copiar; o último erro e o payload, cada um com um botão de copiar; uma tabela das tentativas sem sucesso, as mais novas primeiro (resultado, horário de término, worker e o erro); e um link para os jobs do tipo dele.

A API de administração é GET /api/v1/admin/queue, GET /api/v1/admin/jobs?state=&type=, GET /api/v1/admin/jobs/{id}, GET /api/v1/admin/jobs/{id}/attempts e POST /api/v1/admin/jobs/{id}/retry. Um job concluído não está mais na fila, então a página dele não é encontrada.

  • Os jobs em espera, em execução e aguardando nova tentativa só podem ser listados para as filas cujos jobs o servidor guarda: queue = db, queue = cloudtasks (os jobs também estão no banco de dados) e queue = inline. Os jobs com falha e o histórico de tentativas estão no banco de dados da aplicação para toda fila, então sempre podem ser listados.
  • O histórico de tentativas guarda apenas as tentativas sem sucesso (novas tentativas e a tentativa que por fim falhou). Acompanhe uma execução bem-sucedida pela linha de log estruturada job (que traz job_id). O histórico é removido pela limpeza de hora em hora depois que job_attempt_retention (padrão 30 dias; veja a configuração) passou desde o término da tentativa. O histórico não guarda payload nem log do handler, e uma mensagem de erro é cortada nos primeiros 2.000 bytes. Os handlers de jobs mantêm endereços de e-mail, endereços IP, tokens e corpos de publicações fora das mensagens de erro. Para uma visão limitada aos tipos de job de e-mail, veja Enviando e-mail.

Um job cujo handler decidiu que falhou definitivamente, e um job que esgotou as novas tentativas, vira um job dead na fila do banco de dados (queue = db e queue = cloudtasks). my job os lista, repete e exclui. O estado “Com falha” da página de jobs e a API de administração também podem listá-los e repeti-los.

Janela do terminal
my job list # newest failures first: ID, type, run count, time of failure, last error (-limit sets the count, default 50)
my job retry <id> [<id>...] # reset the attempt count and put the job back in the queue to run immediately
my job delete <id> [<id>...] # remove without running
my job types # print every job type of this release
  • Se um job com a mesma chave de idempotência já está esperando, esse job substitui o repetido. Os handlers de jobs são idempotentes, então colocar o mesmo job de volta qualquer número de vezes é seguro.
  • Um ID desconhecido é impresso e o comando termina com o código 1; os outros IDs ainda são processados. O código de saída 2 significa um erro de uso.
  • Um job dead que ninguém repete é removido pela limpeza de hora em hora depois que dead_job_retention (padrão 30 dias; veja a configuração) passou desde a falha.
  • Os jobs dead de queue = inline ficam na memória do processo do servidor, então my job não consegue tratá-los (código de saída 1).

Por padrão, todo worker executa todo tipo de job, na ordem em que os jobs venceram, um job por vez em cada processo (veja Executando vários jobs ao mesmo tempo). Uma rajada de entregas então atrasa o e-mail e as notificações, e qualquer worker que você adicionar divide o tempo dele entre todos eles. Com queue = db, você pode dar a alguns tipos os próprios workers:

Cada uma é uma lista separada por vírgulas de tipos de job (my job types os exibe; my config check recusa um nome que não corresponde a nenhum), escritos como um nome (federation.deliver) ou um prefixo (federation.*). Defina-as por processo, por exemplo com MY_WORKER_JOB_TYPES. Não é possível definir as duas em um mesmo processo. Um nome ou prefixo que não corresponde a nenhum tipo de job impede o início, o que também detecta um tipo que uma versão renomeou, ou um tipo que só existe com uma configuração que você não definiu. Elas não funcionam com role = web, nem com queue = cloudtasks ou inline, em que o início também falha: ali um sinal nomeia o job a executar, então um processo não pode escolher os seus jobs.

No início, um processo com uma das configurações registra no log os tipos que ignora. Ele não enxerga as configurações dos outros processos, então garanta que algum processo execute todos os tipos, ou esses jobs esperarão para sempre. A limpeza periódica e o e-mail também são tipos de job. Todo processo ainda inicia os jobs periódicos; qual processo os executa depende dessas configurações.

Decida o que dividir a partir das métricas, não dos nomes dos tipos. my.job.wait (Prometheus: my_job_wait_seconds) mostra quanto tempo os jobs esperaram por tipo antes de começar:

histogram_quantile(0.95, sum by (my_job_type, le) (rate(my_job_wait_seconds_bucket[15m])))

sum by (my_job_type) (rate(my_job_duration_seconds_sum[1h])) mostra o tempo de worker que cada tipo usa, que também é aproximadamente quantos processos ele precisa. Um tipo que usa a maior parte do tempo e faz os outros esperarem é o que deve ser movido.

Três layouts comuns, com o número de processos à sua escolha:

Layout Processos
Evitar que as entregas atrasem o resto worker_job_types = federation.fanout,federation.deliver para as entregas, e worker_job_types_except = federation.fanout,federation.deliver para todo o resto. Adicione processos ao primeiro grupo durante uma rajada.
Evitar que um backend de busca atrase o resto worker_job_types = search.* para os jobs de busca, e worker_job_types_except = search.* para todo o resto (Evitando que a busca atrase outros jobs).
Manter o e-mail e as notificações rápidos worker_job_types = identity.verification_email,identity.password_reset_email,identity.password_notice_email,identity.closure_email,identity.deactivation_email,notification.email,notification.moderator_email,notification.supporter_email,notification.push,notification.post_subscribers,instance.notify_announcement,voice.notify_started para esses, e um worker sem configuração para todos, o que também ajuda com esses tipos quando está livre. Deixe de fora os tipos de configurações que você não definiu, ou o início falha: notification.push precisa de vapid_private_key, e notification.email, notification.moderator_email e notification.supporter_email precisam de mail. Veja Jobs que dependem de configurações.

Um prefixo como identity.* é o módulo de código que possui os tipos, não um tipo de trabalho. identity.* também pega exportações de dados, importações e jobs de expiração, e não pega instance.notify_announcement nem voice.notify_started; portanto, um layout para um tipo de trabalho nomeia cada tipo.

Mantenha estes juntos, em workers com a mesma configuração. Os jobs de uma mesma chave de ordenação executam em ordem, qualquer que seja o tipo; assim, se nada executa o job anterior, o posterior também espera, e se o grupo do job anterior está congestionado, o job posterior espera por ele:

Tipos O que mantêm em ordem
federation.fanout, federation.deliver As entregas de um like e do desfazer dele
voice.apply_media_event, voice.apply Os eventos de uma sala de voz
supporters.sync, supporters.command As mudanças de uma assinatura

Ao atualizar:

  • Um processo com worker_job_types não executa os tipos que uma nova versão adiciona. Confira as notas da versão e os tipos ignorados no log. Um processo com worker_job_types_except os executa, o que o torna o lugar mais seguro para todo o resto.
  • Um tipo renomeado impede o início, então leia primeiro as notas da versão.

Para implantar uma divisão, inicie primeiro os novos workers e depois adicione a configuração aos antigos. Para desfazê-la, remova a configuração de um grupo antes de parar o outro. Os jobs permanecem na fila, então nada se perde, e um tipo que ninguém executa por um tempo apenas espera.

Detectando um tipo que nada executa. Os jobs desse tipo esperam, então my.queue.oldest_ready_age cresce para ele, e os alertas MyQueueBacklog e MyQueueStalled disparam para o tipo que espera há mais tempo. Para ver qual é, ou para criar alertas por tipo:

max by (my_job_type) (my_queue_oldest_ready_age_seconds) > 1800

A página de jobs da administração mostra a mesma espera por tipo. Um worker com uma das configurações também deixa de lado um job cujo tipo não tem nenhum handler (ele conta como other na métrica); assim, sem nenhum worker sem configuração, esse job espera em vez de virar um job dead.

worker_job_concurrency define quantos jobs um processo executa ao mesmo tempo, de 1 a 128. Ele funciona com queue = db; com o Cloud Tasks a plataforma decide. O padrão é um job por vez, e uma configuração de 1 se comporta do mesmo modo.

Aumente-o para jobs que passam o tempo esperando por outros servidores, como federation.deliver. Esses usam pouca memória e poucas conexões de banco de dados por job, então um processo faz o trabalho de muitos: em um teste local em que um job só esperava 200 ms por uma resposta, um processo com 32 slots igualou 32 processos com um slot cada, usando uma pequena parte da memória. Esses jobs não faziam mais nada, então meça a sua própria instância. Combine-o com worker_job_types e dê a cada tipo de job um processo com o número próprio.

Tenha estes limites em mente:

  • Conexões de banco de dados: um job precisa de uma conexão para ser reivindicado, para o próprio trabalho e para registrar o resultado. A configuração precisa ficar abaixo do máximo do pool, ou o servidor não inicia. O máximo é pool_max_conns em database_url, por padrão o maior entre 4 e a contagem de CPUs, então uma vCPU permite 3 até você aumentá-lo. Confira se o seu banco de dados ou pooler de conexões aceita as conexões de todos os seus processos.
  • SQLite: ele grava uma transação por vez, e em um teste local ficou mais lento com 128 do que com 32.
  • Jobs pesados de CPU: os slots compartilham a CPU e a memória de um processo. media.process espera a vez em um limite de metade das CPUs por padrão, e a espera conta contra o lease de 5 minutos do job, então um processo cheio de media.process pode passar do lease e recomeçar. Dê a esses jobs um processo com poucos slots.
  • Um servidor por vez: um processo faz no máximo 8 conexões com qualquer host, então um processo entrega a um único servidor não mais rápido do que 8 conexões permitem, não importa quantos slots tenha. Onde a maioria das entregas vai para alguns servidores grandes, mais processos ajudam onde mais slots não ajudam.
  • Um servidor travado segura slots: os slots esperando um servidor lento não ficam livres para outros jobs, então mantenha as entregas separadas do e-mail e das notificações.
  • Implantações gastam tentativas: quando o servidor para, os jobs ainda em execução depois de ShutdownTimeout (25 segundos por padrão) são cancelados, e cada job cancelado gasta uma tentativa. Quanto mais slots executam jobs lentos, mais tentativas cada implantação gasta. Um job cancelado cujo resultado não é registrado a tempo espera o lease expirar antes de executar de novo.
  • Uma queda leva todos os slots junto: se o processo fica sem memória, todos os jobs dele esperam os leases expirarem.

Para decidir se vale aumentá-lo, leia my.job.wait por my.job.type: se os jobs de um tipo esperam muito enquanto my.job.duration é em grande parte tempo gasto esperando outros servidores e a CPU e a memória continuam baixas, mais slots devem ajudar. Se as esperas continuam altas depois de aumentá-lo, olhe as conexões de banco de dados e o limite por host acima antes de aumentá-lo de novo.

Enquanto nenhum job está vencido, um slot faz polling e os outros esperam, então um processo ocioso custa ao banco de dados o que um processo de um job custa.

Com database = postgres, cada instrução e transação primeiro espera uma conexão livre do pool do processo. database_acquire_timeout (padrão 60s) limita essa espera, e nada além dela: uma consulta ou transação longa que já tem a sua conexão continua, por mais que demore. 0 espera sem limite. O SQLite não tem limite de conexões a esperar, então defini-la ali falha na inicialização.

Quando a espera acaba:

  • Uma requisição é respondida com 503 Service Unavailable e Retry-After: 5.
  • Um job executa de novo 30 segundos depois e não consome nenhuma tentativa, de modo que um banco de dados ocupado nunca transforma um job em um job dead.
  • A métrica db.client.connection.timeouts a conta, e o alerta MyDBPoolWaiting dispara.

O padrão é o timeout de escrita de 60 segundos do servidor: uma requisição que esperou mais não poderia enviar a resposta de qualquer forma, então o padrão não faz falhar nenhuma requisição que ainda poderia ter dado certo. Escolha um valor conforme o funcionamento da sua instância:

  • Reduza-o para descartar carga rapidamente: os clientes tentam de novo após Retry-After em vez de manter as requisições abertas. Mantenha-o maior que as suas transações normais mais lentas, ou uma rajada curta passa a responder 503.
  • Dimensione o pool primeiro. Um processo precisa de aproximadamente tantas conexões quanto o trabalho que executa ao mesmo tempo. pool_max_conns em database_url tem como padrão o maior entre 4 e o número de CPUs, e todos os processos juntos devem ficar abaixo do limite de conexões do banco de dados.
    • Com worker_job_concurrency, os slots também esperam conexões, e a configuração deve ficar abaixo do máximo do pool.
    • No Cloud Run, um serviço aceita 80 requisições simultâneas por instância por padrão. Com um pool de 4, uma rajada de requisições lentas forma fila aqui; portanto, aumente pool_max_conns, reduza a concorrência do serviço, ou ambos.
  • 503 frequentes ou db.client.connection.timeouts significam que o pool é pequeno demais ou que as consultas ficaram mais lentas; um timeout maior apenas esconde isso. Siga MyDBPoolSaturated.

Implantando no Cloud Run configura tudo o que está abaixo com módulos do OpenTofu.

Com queue = cloudtasks, os jobs permanecem no banco de dados (database = postgres), e o Google Cloud Tasks apenas acorda o servidor para cada um deles:

  • Para cada job que guarda, repete ou recoloca na fila, o servidor cria uma task em queue_cloudtasks_queue depois que a transação é confirmada. A task chama POST {queue_cloudtasks_url}/_internal/jobs no horário em que o job vence, com o ID do job como corpo e um token de ID OIDC de queue_cloudtasks_service_account. Um job que vence com mais de 30 dias de antecedência é sinalizado aos 30 dias, e de novo quando essa task chega.
  • O processo que recebe a task executa o job e responde 204 assim que o resultado é registrado, também quando o job já executou ou não está vencido. Um job que falha é repetido pelo servidor no próximo horário de tentativa dele, não pelo Cloud Tasks. O Cloud Tasks repete uma task apenas quando a resposta é 5xx (o banco de dados não pôde ser alcançado) ou 401 (um token que o servidor recusou), então o retryConfig dele não precisa de ajuste.
  • Nenhum processo faz polling da tabela e nenhum processo executa os jobs periódicos por conta própria. Crie um job do Cloud Scheduler que chame POST {queue_cloudtasks_url}/_internal/tick a cada minuto (* * * * *) com um token OIDC da mesma conta de serviço (e a audiência de queue_cloudtasks_audience, quando definida). Cada tick enfileira os jobs periódicos cujo período chegou, uma vez para a instância inteira (os períodos são reivindicados no KV, então kv deve ser db ou valkey), e sinaliza de novo os jobs que estão vencidos há mais de 2 minutos sem executar, o que recupera um sinal perdido.
  • /_internal/jobs e /_internal/tick são servidos pelos processos com role = all ou worker, e aceitam apenas um token assinado pelo Google para queue_cloudtasks_service_account com um e-mail verificado, cuja única audiência é queue_cloudtasks_audience ou, por padrão, a URL chamada. Qualquer outra requisição recebe 401.
  • Uma entrega executa um job, por no máximo o lease de 5 minutos. Mantenha queue_cloudtasks_dispatch_deadline (padrão 10 minutos) e o timeout de requisição do serviço do Cloud Run maiores que isso.
  • A própria conta de serviço do servidor precisa de roles/cloudtasks.enqueuer na fila e de roles/iam.serviceAccountUser em queue_cloudtasks_service_account. Ela se autentica com as Application Default Credentials.

Um job periódico executa até um período do seu gatilho depois do horário dele, mais o tempo que a plataforma leva para iniciá-lo. É isso que decide com que atraso chegam os lembretes e as notificações de início dos eventos e abrem as salas de chat de voz deles, já que gathering.tick os inicia: um lembrete se atrasa em até o intervalo da tabela. Os valores são os que o código do agendador e o gatilho de cada plataforma dão; eles não foram medidos em um servidor em execução.

Plataforma O que inicia os jobs periódicos Atraso esperado de um lembrete ou início de evento
Hospedagem própria e Docker Compose (queue = db) O agendador em cada processo com role = all ou worker verifica uma vez por minuto, a partir de quando o processo iniciou, e enfileira cada job uma vez por período para o servidor inteiro Até 1 minuto, mais cerca de um segundo para um worker pegar o job
AWS ECS Fargate (queue = db) O mesmo agendador, nas tasks de worker Até 1 minuto, mais cerca de um segundo
Cloud Run (queue = cloudtasks) O Cloud Scheduler chama /_internal/tick no horário dele, * * * * * (a cada minuto) por padrão; o Cloud Tasks então acorda o servidor para cada job Até 1 minuto, mais o início de uma instância quando nenhuma está em execução (um cold start, em geral alguns segundos). Com um tick_schedule mais longo, como */10 * * * *, até esse intervalo
AWS Lambda O my não tem implantação no Lambda; na AWS, execute-o no ECS Fargate —

Um lembrete que chegaria depois de o evento começar não é enviado, e uma notificação de início também não depois de o evento terminar. Então, com um tick maior que 5 minutos, os lembretes mais curtos podem se perder.

Com queue = cloudtasks, um worker não pode escolher os jobs que executa: worker_job_types funciona apenas com queue = db, porque a plataforma decide quem recebe um sinal. Para dar a alguns tipos de job capacidade própria, envie os sinais deles para uma fila própria e defina a capacidade dessa fila na plataforma. Nada muda a menos que você defina uma rota.

queue_cloudtasks_routes: federation.*=projects/p/locations/l/queues/my-federation@https://federation-worker.example.com,notification.email=projects/p/locations/l/queues/my-mail. Uma rota sem @ e uma URL chama queue_cloudtasks_url.

O lado esquerdo é um tipo de job da referência de jobs ou um prefixo. Um nome vence um prefixo, e um prefixo mais longo vence um mais curto. Os tipos que não correspondem a nenhuma rota, incluindo os que uma versão futura adicionar, usam a fila padrão (queue_cloudtasks_queue), então continuam executando. my config check verifica o formato das rotas; um lado esquerdo que não corresponde a nenhum tipo de job impede my serve de iniciar.

Dê as mesmas rotas a todos os processos, role = web inclusive. Um sinal é enviado pelo processo que guarda o job: um processo web para a maior parte do que os usuários fazem, como o primeiro job de uma publicação, e um worker para os jobs que um job guarda, as novas tentativas, o próximo job de uma chave de ordenação e a varredura de sinais perdidos. Onde cada função tem as próprias configurações, como os serviços do Cloud Run, passe o mesmo valor a todos:

Janela do terminal
routes='federation.*=projects/p/locations/l/queues/my-federation@https://federation-worker.example.com'
gcloud run services update my-web --update-env-vars "^|^MY_QUEUE_CLOUDTASKS_ROUTES=$routes"
gcloud run services update my-worker --update-env-vars "^|^MY_QUEUE_CLOUDTASKS_ROUTES=$routes"
gcloud run services update my-federation-worker --update-env-vars "^|^MY_QUEUE_CLOUDTASKS_ROUTES=$routes"

Um processo com outras rotas não gera erro e não perde nenhum job: os sinais dele vão para outra fila, e os jobs executam lá, fora da capacidade que você definiu. my.queue.oldest_ready_age não mostra isso, porque esses jobs não esperam. Para comparar os processos, cada um registra no log ao iniciar uma linha com as suas routes e o routes_hash delas: o hash tem de ser o mesmo em todos os lugares. Para ver para onde os sinais vão, leia as métricas da própria plataforma de cada fila.

Permissões. As credenciais de cada processo precisam enviar para toda fila das rotas: roles/cloudtasks.enqueuer. Um envio que falha é registrado no log e não é tentado em outra fila, para que um tipo que você limita não transborde para os outros. Esses jobs começam atrasados, quando a varredura envia os sinais deles de novo após 2 minutos.

Capacidade. Qualquer receptor executa qualquer job, então você escolhe até onde separá-los:

Plataforma Um receptor Receptores separados
Google Cloud Um serviço. Cada fila tem os próprios maxConcurrentDispatches e maxDispatchesPerSecond; o limite de instâncias do serviço é compartilhado Um serviço por fila, nomeado pela URL na rota, cada um com o próprio limite de instâncias e concorrência. Cada um define queue_cloudtasks_url com a própria URL

Uma fila precisa da mesma configuração que a padrão: a função na fila. Apenas a fila padrão precisa do tick.

O que uma fila acrescenta. Cada fila é mais uma coisa para criar, acompanhar e pagar, e o quanto isso importa depende do tamanho da sua instância. Divida o que você viu esperando em my.job.wait, não tudo.

A varredura. A cada minuto, a varredura procura jobs vencidos há mais de 2 minutos sem executar, até 500 por rota e 500 para a fila padrão, e os sinaliza de novo. Assim, uma fila que não dá conta recebe até 500 sinais duplicados por minuto. Eles não executam um job duas vezes, mas são mensagens que você paga, e cessam quando o acúmulo se esgota.

As chaves de ordenação continuam valendo: o banco de dados decide o que pode executar. Os jobs de uma chave podem estar em filas diferentes, mas uma fila parada também atrasa os jobs posteriores das suas chaves.

Adicionando, movendo e removendo uma fila.

  1. Crie a fila e o receptor dela, e dê a todos os processos permissão para enviar a ela.
  2. Altere as rotas em todos os processos. Enquanto elas diferem, os sinais vão para qualquer uma das filas e os jobs executam nos dois lugares.
  3. Para remover uma fila, tire-a das rotas em todos os lugares primeiro, e espere até que esteja vazia antes de excluí-la. Um sinal em uma fila excluída se perde, mas não o job: a varredura sinaliza o job de novo quando ele estiver vencido há 2 minutos. Uma task do Cloud Tasks pode guardar o sinal de um job com até 30 dias de antecedência, então um job que vence depois da espera é simplesmente sinalizado pela varredura quando chega a hora dele.
Caminho Tipo Quando retorna 200
GET /healthz, GET /health/live liveness O processo consegue responder HTTP. Ele não olha dependências como o banco de dados (para que um banco de dados lento não reinicie o processo)
GET /readyz, GET /health/ready readiness O banco de dados está acessível e o schema foi aplicado
GET /api/v1/instance/health Monitoramento de disponibilidade, páginas de status e clientes (servido pela função web) O mesmo que a readiness. O resultado fica em cache no processo por 60 segundos
  • O Cloud Run reserva alguns caminhos que terminam em z, /healthz entre eles, e os responde por conta própria com um 404; atrás dele, chame /health/live e /health/ready, que respondem o mesmo.
  • Um 200 de qualquer um deles tem o corpo {"status":"ok"}.
  • /readyz verifica o banco de dados a cada requisição, e as requisições simultâneas compartilham uma verificação.
  • /api/v1/instance/health retorna 200 e {"status":"ok","checked_at":"<RFC 3339>"} quando saudável, e 503 e {"status":"unavailable","checked_at":...} em caso de falha (Cache-Control: no-store). Cada processo toca o banco de dados no máximo uma vez por minuto, não importa com que frequência seja monitorado ou requisitado, e não olha nem o token de acesso nem o limite de requisições. Aponte os monitores de disponibilidade para este endpoint, não para a probe (/readyz ou /health/ready). Para a configuração por serviço, o intervalo de monitoramento e o custo, e como a manutenção é tratada, veja o guia de monitoramento de disponibilidade.
  • Os três registram no nível Debug no log de acesso e não criam span de trace.
  • Quando a readiness não é atendida, a resposta é 503 com um corpo RFC 9457 application/problem+json. O title dele é traduzido conforme o Accept-Language e não contém detalhes internos. A causa (um erro de conexão ou os nomes das tabelas ausentes) vai para o log.
  • Uma verificação de readiness é interrompida após 3 segundos.
  • A readiness também exige que o banco de dados contenha o host e o account_domain configurados, ou que o processo consiga registrá-los.
  • Schema aplicado significa que toda tabela que os arquivos de schema do banco de dados (schema/<NN>-<module>/<dialect>.sql) declaram com CREATE TABLE existe (o SQLite é verificado por sqlite_schema, o PostgreSQL por current_schema() da conexão). my schema apply aplica o schema inteiro, então uma tabela ausente significa que o schema não foi aplicado ou é mais antigo que o binário. Diferenças de colunas e índices não são verificadas; my schema apply -dry-run exibe o que mudaria.

Quando o servidor está atrás de uma CDN e o próprio endereço dele continua público, defina origin_secret e origin_secret_header para que ele recuse o que não passou pela CDN. As verificações de saúde continuam acessíveis. Veja Recusar requisições que não passaram pela CDN.

Toda resposta traz Strict-Transport-Security, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, Cross-Origin-Opener-Policy, Cross-Origin-Resource-Policy: same-site e X-Frame-Options, e, para as respostas que não são documentos, Content-Security-Policy: default-src 'none'; frame-ancestors 'none'; base-uri 'none'. Um handler os substitui nas respostas que precisam de outros valores, como o JSON do ActivityPub e a mídia pública. Permissions-Policy nega a câmera, a geolocalização, o pagamento e o USB. Nega também o microfone, exceto enquanto o chat de voz está ativado (voice não é off): então ela permite o microfone apenas para as páginas da própria origem do servidor (microphone=(self)), para que os navegadores possam falar em uma chamada. O HTML do cliente web recebe uma CSP de documento que não usa nonce (script-src 'self' e assim por diante). Ela exige Trusted Types (require-trusted-types-for 'script') e limita as políticas que podem ser criadas às duas do cliente (trusted-types my-server-sanitized-html my-service-worker).

Um processo cujo role é web ou all serve o cliente web embutido no binário.

Caminho Conteúdo Cache-Control
Qualquer GET que nenhuma outra rota atende (/, /@alice, /@alice/status/{id}, /settings e assim por diante) O shell HTML do SPA. As configurações da instância são passadas em <script type="application/json" id="config"> public, max-age=60, stale-while-revalidate=300, ETag
GET /assets/* Arquivos de build com nomes com hash public, max-age=31536000, immutable, ETag
GET /manifest.webmanifest O manifesto do web app construído a partir das configurações da instância public, max-age=60, stale-while-revalidate=300, ETag
GET /sw.js, /icon.svg e outros arquivos diretamente sob o build Servidos como estão no-cache, ETag
GET /licenses/* As licenças do que o build empacota (avisos dos pacotes npm, e LICENSE-Unicode.txt e OFL.txt para dados não npm empacotados). Servidos como text/plain; charset=utf-8 seja qual for a extensão no-cache, ETag
GET /robots.txt, /.well-known/tdmrep.json, /.well-known/security.txt Construídos a partir das configurações da instância (veja Mecanismos de busca e rastreadores de IA) public, max-age=3600, ETag
  • Os caminhos sob /api, /oauth, /auth, /.well-known, /nodeinfo, /ap, /media, /uploads, /theme (a folha de estilo do tema do servidor) e /licenses, e /robots.txt, nunca retornam o shell; se nenhuma outra rota os atende, retornam um problema 404.
  • O shell é servido depois da negociação de conteúdo do ActivityPub. Requisitar um caminho do shell com um Accept do ActivityPub retorna 404 (as páginas de publicação redirecionam, como descrito abaixo). O shell sempre traz Vary: Accept. Quando você coloca uma CDN na frente, inclua o tipo de Accept (ActivityPub ou HTML) na chave de cache, ou exclua o shell, /ap/* e /@* do cache. Sirva apenas /assets/* pela CDN.
  • Os arquivos de texto do build (scripts, folhas de estilo, imagens SVG, avisos de licença) são embutidos apenas comprimidos. Uma requisição que aceita Brotli os recebe com Content-Encoding: br, uma que aceita gzip com Content-Encoding: gzip, e qualquer outra requisição os recebe descomprimidos, sempre com Vary: Accept-Encoding e um ETag para cada codificação. Um proxy na frente não precisa de compressão própria para eles, e uma CDN precisa manter Vary: Accept-Encoding (ou a codificação) na chave de cache de /assets/*.
  • O shell e as telas de login trazem cabeçalhos Link que nomeiam as folhas de estilo e o script de entrada que a página carrega primeiro, a partir dos quais uma CDN como a Cloudflare (o recurso Early Hints dela) pode fazer early hints próprios. Com web_early_hints = true, o servidor também os envia primeiro em uma resposta 103 Early Hints, para que o navegador busque os arquivos enquanto o servidor prepara a página. Ele vem desativado por padrão, já que um proxy que não consegue repassar um 103 pode fazer a requisição falhar:
    • Um Application Load Balancer externo do Google Cloud responde 502 ou 503 (backend_interim_response_not_supported): deixe desativado atrás de um, como faz a implantação no Cloud Run.
    • O nginx o repassa a partir da 1.29.0, com early_hints definido.
    • O reverse_proxy do Caddy o repassa; uma diretiva encode o descarta em versões anteriores à 2.8.
    • Os navegadores usam um 103 apenas para uma página a que navegam, e o Chrome e o Edge apenas por HTTP/2 e HTTP/3.
  • Um binário construído sem o cliente web (um simples go build, sem construir o cliente antes) registra um aviso na inicialização e serve um shell sem scripts.

Um processo cujo role é web ou all responde a estes endpoints, que outros servidores do fediverso usam para encontrar e exibir as suas contas.

Caminho Conteúdo
GET /.well-known/webfinger WebFinger (RFC 7033). resource é acct:alice@{account_domain} (acct:alice@{host} também funciona), o id de um Actor ou a URL /@alice. subject é sempre o handle do lado do account_domain
GET /.well-known/host-meta, /.well-known/host-meta.json O modelo de URI do WebFinger (XRD / JRD)
GET /.well-known/nodeinfo, GET /nodeinfo/2.1 NodeInfo 2.1. metadata.sourceCode é a configuração source_url, e software.repository também é definido para uma URL https: (veja Publicar o código-fonte)
GET /ap/actors/{uuid} O Actor (publicKey é o #main-key RSA). Uma requisição que prefere HTML recebe um 303 para /@{username}
GET /ap/actors/{uuid}/{outbox,followers,following,featured,featured-tags} Coleções
POST /ap/actors/{uuid}/inbox, POST /ap/inbox A inbox de cada actor local e a inbox compartilhada. As requisições devem ter assinatura HTTP
GET /@{username} Um 302 para o id do Actor com um Accept do ActivityPub; caso contrário, o HTML do cliente web (veja abaixo)
GET /@{username}/status/{uuid} Com um Accept do ActivityPub, um 302 para o id (/ap/objects/{uuid}) da publicação se um visitante sem login pode vê-la, e 404 se não. Caso contrário, o HTML do cliente web
  • O handle do Actor da instância é {account_domain}@{account_domain} (a mesma forma do Mastodon).
  • Uma conta que não existe ou não pode ser exibida (suspensa, desativada, excluída ou remota) sempre recebe o mesmo 404 (Cache-Control: no-store).
  • As respostas anônimas trazem Cache-Control: public, max-age=60. As respostas que variam por Accept trazem Vary: Accept. Para uma CDN que não consegue tratar Vary: Accept, exclua do cache /ap/* e /@*.

Quando account_domain difere de host, as requisições a /.well-known/webfinger, /.well-known/host-meta e /.well-known/nodeinfo do lado do account_domain são redirecionadas para host com um 301 (com Access-Control-Allow-Origin: *). Se você encaminha as requisições de account_domain para este servidor, o próprio servidor devolve esse redirecionamento. Se outro servidor ou proxy reverso responde no lugar, redirecione para https://{host} mantendo o caminho e a query string.

Para LLMs e agentes de programação:llms.txt,llms-full.txt, llms-small.txt

Análise de acesso deste site