From 38c01e4e5989196bf9248bcf6fe38297834d77f5 Mon Sep 17 00:00:00 2001 From: Thijs van Emmerik Date: Tue, 2 Jun 2026 17:27:00 +0000 Subject: [PATCH 1/4] docs: document escalation contacts and user management --- docs/contribute-ops-management.md | 72 ++++++++++++++++++++++++++++++- 1 file changed, 71 insertions(+), 1 deletion(-) diff --git a/docs/contribute-ops-management.md b/docs/contribute-ops-management.md index da8de06..e902945 100644 --- a/docs/contribute-ops-management.md +++ b/docs/contribute-ops-management.md @@ -45,11 +45,13 @@ doublezero contributor update \ Once authenticated, the **Incident Tracking Table** shows. +Account settings live behind the **Settings** menu (the gear icon, top right): API Key Management, User Management, and Escalation Contacts. The options you see depend on your role. + ### 3. Create API Keys (Optional) For programmatic access instead of the web form: -1. Click **Manage API Keys** on the portal. +1. Open the **Settings** menu (gear icon) and choose **API Key Management**. 2. Create one or more API keys. 3. Download the API documentation from this page. @@ -214,6 +216,72 @@ planned → in-progress → completed → closed (auto 24h after end_at) --- +## Escalation Contacts + +Escalation contacts tell DoubleZero and other contributors who to reach when your part of the network has a problem. You set up your own contacts for your organization. A contact can be a person or a team, such as your NOC. Each contact has one or more ways to reach it and a schedule for when it is on call. + +Open the **Settings** menu (gear icon) and choose **Escalation Contacts**. Only ops managers can add or edit contacts. + +### Adding a Contact + +For each contact, set: + +| Field | Description | +|-------|-------------| +| Name | A name for the contact, whether a person or a team such as your NOC | +| Timezone | The local timezone, used to read the schedule | +| Availability | **24/7**, or one or more weekly time slots when the contact is on call | +| Contact methods | One or more ways to reach the contact, in priority order | + +Supported contact methods are email, phone, Slack, Telegram, and WhatsApp. Order matters: the first method is the one to try first. + +### Availability and Coverage Gaps + +A contact is either available around the clock (24/7) or available during weekly time slots you define, for example Monday to Friday, 09:00 to 17:00. Slots are entered in the contact's local timezone and shown in UTC, so daylight saving is handled for you. + +The **coverage gaps** view shows the times each week when no one from your organization is on call. Use it to find and close gaps. + +### Rotation Windows + +The week is split into half-hour windows. For each window you can set the order in which your contacts are reached. This lets you run an on-call rotation without editing each contact. + +### Visibility + +You control who can see your contacts. DoubleZero can always see them. You choose who else can: + +| Setting | Who else can see your contacts | +|---------|-------------------------------| +| DoubleZero only (default) | No other contributors | +| Everybody | All contributors | +| Some contributors | Only the contributors you select | + +Your own team can always see your contacts. Visibility is set once for your whole organization and applies to all your contacts. + +--- + +## User Management + +By default, your Ops Manager key is the only account that can act for your organization. You can add team members so more than one person can manage your tickets. + +Open the **Settings** menu (gear icon) and choose **User Management**. Only ops managers can add or remove team members. + +For each team member, set: + +| Field | Description | +|-------|-------------| +| Name | The person's name | +| Wallet pubkey | The Solana wallet they sign in with | +| Access level | **Read** or **Read-write** | + +Access levels: + +- **Read**: can view tickets and escalation contacts, and create read-only API keys. Cannot create, update, or close tickets. +- **Read-write**: full access to create, update, and close tickets, and can create API keys of any level. + +Each team member signs in with their own wallet, the same way you connected your Ops Manager key. + +--- + ## Permissions and Escalation ### What Contributors Can Do @@ -221,6 +289,8 @@ planned → in-progress → completed → closed (auto 24h after end_at) - Create and manage tickets for their own devices and links only. - Assign tickets to themselves or escalate to DZ/Malbeclabs. - View all tickets across all contributors. +- Add team members and set their access level (ops managers only). +- Manage escalation contacts for their organization (ops managers only). ### What DZ/Malbeclabs Admins Can Do From 9fe0cc126de838b21d146dc13fb3ef82f7a21fe8 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 2 Jun 2026 17:39:17 +0000 Subject: [PATCH 2/4] chore: auto-translate docs --- docs/contribute-ops-management.es.md | 313 +++++++++++++++++++++++++++ docs/contribute-ops-management.fr.md | 313 +++++++++++++++++++++++++++ docs/contribute-ops-management.it.md | 313 +++++++++++++++++++++++++++ docs/contribute-ops-management.ja.md | 313 +++++++++++++++++++++++++++ docs/contribute-ops-management.ko.md | 313 +++++++++++++++++++++++++++ docs/contribute-ops-management.pt.md | 313 +++++++++++++++++++++++++++ docs/contribute-ops-management.zh.md | 313 +++++++++++++++++++++++++++ 7 files changed, 2191 insertions(+) create mode 100644 docs/contribute-ops-management.es.md create mode 100644 docs/contribute-ops-management.fr.md create mode 100644 docs/contribute-ops-management.it.md create mode 100644 docs/contribute-ops-management.ja.md create mode 100644 docs/contribute-ops-management.ko.md create mode 100644 docs/contribute-ops-management.pt.md create mode 100644 docs/contribute-ops-management.zh.md diff --git a/docs/contribute-ops-management.es.md b/docs/contribute-ops-management.es.md new file mode 100644 index 0000000..df311dc --- /dev/null +++ b/docs/contribute-ops-management.es.md @@ -0,0 +1,313 @@ +# Gestión OPS + +El portal de Gestión OPS de DoubleZero es donde los contribuidores registran y hacen seguimiento de incidentes (interrupciones no planificadas) y mantenimientos (trabajos planificados) en toda la red. Todos los tickets son visibles para todos los contribuidores. + +**Portal:** [https://doublezero.xyz/ops-management](https://doublezero.xyz/ops-management) + +## Portal vs Slack + +El portal de Gestión OPS y Slack trabajan juntos. Todos los incidentes y mantenimientos se registran como tickets, accesibles a través del portal o la API. Cada ticket notifica automáticamente a los canales de Slack correspondientes y proporciona a cada contribuidor una vista compartida de lo que está ocurriendo en la red. Slack es donde sucede la conversación: compartir registros, coordinarse con otros contribuidores y colaborar en problemas activos. + +Los tickets son el registro canónico, ya sean creados a través del portal o la API. Los hilos de Slack no lo son: no actualizan el estado del ticket y no se almacenan de forma permanente. Mantén siempre el estado del ticket actualizado, incluso si la conversación está ocurriendo en Slack. + +El portal y Slack sirven para propósitos diferentes. Usa ambos, pero para las cosas adecuadas. + +| Usa el portal (o la API) para... | Usa Slack para... | +|-------------------------------|-----------------| +| Abrir, actualizar y cerrar tickets | Conversación y colaboración sobre un problema activo | +| Registrar transiciones de estado | Compartir registros, capturas de pantalla o iniciar una llamada | +| Asignar o escalar un ticket | Conseguir atención rápida sobre un problema | +| Establecer la causa raíz al cerrar | Coordinarse con otros contribuidores | + + + +--- + +## Incorporación + +Completa estos pasos una vez antes de usar el portal. + +### 1. Configura tu clave de Ops Manager + +Registra una pubkey de wallet de Solana como tu clave de Ops Manager. Wallets compatibles: Phantom, Solflare, Coinbase Wallet. + +```bash +doublezero contributor update \ + --ops-manager \ + --pubkey +``` + +### 2. Conecta tu wallet en el portal + +1. Navega a [https://doublezero.xyz/ops-management](https://doublezero.xyz/ops-management). +2. Haz clic en **Connect Your Wallet** y selecciona tu wallet. +3. Firma el mensaje para demostrar la propiedad de tu clave de Ops Manager. + +Una vez autenticado, se muestra la **Tabla de seguimiento de incidentes**. + +La configuración de la cuenta se encuentra detrás del menú **Settings** (el icono de engranaje, arriba a la derecha): Gestión de claves API, Gestión de usuarios y Contactos de escalación. Las opciones que ves dependen de tu rol. + +### 3. Crear claves API (opcional) + +Para acceso programático en lugar del formulario web: + +1. Abre el menú **Settings** (icono de engranaje) y elige **API Key Management**. +2. Crea una o más claves API. +3. Descarga la documentación de la API desde esta página. + +--- + +## Incidentes + +Un incidente es un evento no planificado que impacta el servicio. + +### Niveles de severidad + +Asigna la severidad según el impacto en la red de DoubleZero. Puedes actualizar la severidad a medida que la situación evoluciona. + +| Severidad | Impacto | Respuesta | +|----------|--------|----------| +| `sev1` | Interrupción total o rotura importante del plano de control/datos sin alternativa | Deja todo inmediatamente, incluso fuera del horario laboral. Escala a la Fundación DoubleZero de inmediato. | +| `sev2` | Impacto parcial pero sustancial; servicio degradado con posible alternativa | Tratar como urgente. Coordinar activamente. Se requiere respuesta nocturna para degradación sostenida. | +| `sev3` | Impacto limitado o no visible para el usuario; potencial de escalar si no se resuelve | Máxima prioridad durante el horario laboral. Monitorear de cerca. No se requiere escalación fuera de horario a menos que el impacto aumente. | + +??? note "Ejemplos de severidad" + + **Ejemplos de Sev1** + + - Más del 10% del tráfico de usuarios descartado en DoubleZero, sin alternativa a internet público + - Más del 80% de los intentos de incorporación, conexión o desconexión de usuarios fallando + - Más del 20% de los DZDs reportando errores de interfaz + - El controlador devolviendo configuraciones válidas pero incorrectas a los agentes DZD + + **Ejemplos de Sev2** + + - Más del 20% de los usuarios sin poder enviar/recibir tráfico por túneles de DoubleZero, pero con alternativa a internet público + - 0–10% del tráfico de usuarios descartado en DoubleZero sin alternativa + - 20–80% de los nuevos intentos de incorporación, conexión o desconexión de usuarios fallando + - Más del 20% de los agentes de configuración sin poder aplicar la configuración de DZD + - 0–20% de los DZDs reportando errores de interfaz + - Problemas upstream causando pérdida de observabilidad (monitoreo/alertas caídos) + - Pipeline de datos onchain caído o produciendo datos incorrectos + - Más del 20% de la recolección o envío de latencia de internet fallando + - Controlador inaccesible por los agentes DZD + - Controlador devolviendo configuraciones inválidas a los DZDs que no serán aplicadas + + **Ejemplos de Sev3** + + - 0–20% de los usuarios sin poder enviar/recibir tráfico por túneles de DoubleZero, con alternativa a internet público + - 0–20% de los DZDs reportando errores de interfaz + - 0–20% de los DZDs experimentando fallos del agente de configuración + - 0–20% de los intentos de incorporación, conexión o desconexión de usuarios fallando + - Más del 20% de la recolección o envío de latencia de internet fallando para un solo proveedor de datos + - 0–20% de la recolección o envío de latencia de internet fallando para todos los proveedores de datos + - Bugs o deuda técnica causando ruido en las alertas que no puede ser silenciado + - DIA caído o problemas de red del ledger RPC para 0–20% de los dispositivos durante varias horas + - Problemas de bajo impacto como bugs menores, errores cosméticos o incidentes aislados que no afectan el tráfico de clientes + - Una pequeña fracción de dispositivos reportando errores intermitentes sin interrupción del servicio + +### Abrir un incidente + +Haz clic en **Create New Record**, selecciona Type = **Incident** en el portal, o envía a través de la API. + +**Obligatorio:** + +| Campo | Descripción | +|-------|-------------| +| `title` | Resumen breve (máximo 100 caracteres) | +| `description` | Explicación detallada (máximo 500 caracteres) | +| `severity` | `sev1`, `sev2` o `sev3` | +| `status` | No se puede establecer en un estado terminal (`resolved`, `closed`) al crear | +| Dispositivo y/o Enlace | Al menos uno obligatorio. En el formulario web, selecciona de un desplegable con los códigos de tus dispositivos y enlaces. Al usar la API, pasa las pubkeys correspondientes como `device_pubkey` y/o `affected_link_pubkey`. | + +**Opcional:** + +| Campo | Descripción | +|-------|-------------| +| `reporter_name` / `reporter_email` | Tus datos de contacto | +| `assignee` | Quién es responsable de la resolución | +| `internal_reference` | Tu ID de ticket interno (ej. Jira, ServiceNow) | +| `start_at` | Por defecto es la hora de creación; editable | + +Una vez creado, se publica una notificación en el canal de Slack de incidentes de contribuidores con el ID del ticket, la severidad, los dispositivos/enlaces afectados y el nombre del contribuidor. + +### Actualizar un incidente + +A medida que el incidente progresa, mantén el estado del ticket actualizado. Esta es la señal que otros contribuidores y DZ usan para entender en qué se está trabajando. + +| Estado | Cuándo establecerlo | +|--------|----------------| +| `open` | Estado inicial: problema reportado, aún no se está trabajando en él | +| `acknowledged` | Lo has visto y has tomado responsabilidad | +| `investigating` | Diagnosticando activamente: recopilando registros, verificando métricas | +| `mitigating` | Causa raíz conocida o sospechada; aplicando una solución o alternativa | +| `monitoring` | Solución aplicada; observando para confirmar que se mantiene | +| `resolved` | Problema confirmado como resuelto; **causa raíz obligatoria** | +| `closed` | Completamente finalizado; sin más acciones; **causa raíz obligatoria** | + +``` +open → acknowledged → investigating → mitigating → monitoring → resolved → closed +``` + +Puedes omitir estados si es apropiado. Por ejemplo, saltar directamente de `open` a `investigating` si comienzas a trabajar en ello inmediatamente. Usa siempre el estado más preciso para la situación actual. + +Cada actualización de estado publica una respuesta en el hilo de la notificación original de Slack. + +### Cerrar un incidente + +Para mover un incidente a `resolved` o `closed`, se debe establecer una **causa raíz**. Puedes establecer la causa raíz en cualquier etapa anterior si ya la conoces; se vuelve obligatoria al cerrar. + +| Código | Descripción | +|------|-------------| +| `hardware` | Reparación, reemplazo o actualización de hardware (SFP, NIC, cable, dispositivo) | +| `software` | Corrección, actualización o reinicio de software o firmware | +| `configuration` | Cambio, corrección o reversión de configuración | +| `capacity` | Congestión, límites de capacidad o gestión de tráfico | +| `carrier` | Problema del proveedor de circuito, longitud de onda o cross-connect | +| `network_external` | Problema de red externa fuera del control del contribuidor | +| `facility` | Problema de infraestructura del centro de datos (energía, refrigeración) | +| `fiber_cut` | Daño físico de fibra reparado | +| `security` | Incidente de seguridad mitigado | +| `human_error` | Error operativo corregido | +| `false_positive` | No se encontró ningún problema real tras la investigación | +| `duplicate` | Ya registrado en otro ticket | +| `self_resolved` | Problema resuelto sin intervención | +| `dz_managed` | Problema con un componente de software gestionado por DoubleZero (activator, controller, etc.) | + +--- + +## Mantenimiento + +Un registro de mantenimiento es una actividad planificada y con tiempo limitado que puede afectar la disponibilidad. Créalo con antelación para que otros contribuidores puedan verlo y evitar ventanas conflictivas. + +### Programar un mantenimiento + +Haz clic en **Create New Record** > **Maintenance** en el portal, o envía a través de la API. + +**Obligatorio:** + +| Campo | Descripción | +|-------|-------------| +| `title` | Resumen breve (máximo 100 caracteres) | +| `description` | Explicación detallada (máximo 500 caracteres) | +| `start_at` | Hora de inicio planificada (UTC) | +| `end_at` | Hora de fin planificada (UTC); debe ser posterior a `start_at` | +| Dispositivo y/o Enlace | Al menos uno obligatorio. En el formulario web, selecciona de un desplegable con los códigos de tus dispositivos y enlaces. Al usar la API, pasa las pubkeys correspondientes como `device_pubkey` y/o `affected_link_pubkey`. | + +Una vez creado, se publica una notificación en el canal de Slack de mantenimiento de contribuidores con el ID del ticket, los dispositivos/enlaces afectados, la ventana planificada y el nombre del contribuidor. + +### Gestionar el estado del mantenimiento + +Mantén el estado actualizado a medida que la ventana progresa. + +| Estado | Cuándo establecerlo | +|--------|----------------| +| `planned` | Programado, aún no iniciado | +| `in-progress` | El trabajo ha comenzado | +| `completed` | Trabajo finalizado exitosamente | +| `closed` | Se establece automáticamente 24 horas después de `end_at` | +| `cancelled` | Cancelado antes o durante la ejecución | + +``` +planned → in-progress → completed → closed (auto 24h after end_at) + ↓ ↓ + └──────────┴──→ cancelled +``` + +--- + +## Contactos de escalación + +Los contactos de escalación indican a DoubleZero y a otros contribuidores a quién contactar cuando tu parte de la red tiene un problema. Tú configuras tus propios contactos para tu organización. Un contacto puede ser una persona o un equipo, como tu NOC. Cada contacto tiene una o más formas de contactarlo y un horario de cuándo está de guardia. + +Abre el menú **Settings** (icono de engranaje) y elige **Escalation Contacts**. Solo los ops managers pueden añadir o editar contactos. + +### Añadir un contacto + +Para cada contacto, establece: + +| Campo | Descripción | +|-------|-------------| +| Nombre | Un nombre para el contacto, ya sea una persona o un equipo como tu NOC | +| Zona horaria | La zona horaria local, utilizada para leer el horario | +| Disponibilidad | **24/7**, o uno o más intervalos semanales cuando el contacto está de guardia | +| Métodos de contacto | Una o más formas de contactar, en orden de prioridad | + +Los métodos de contacto admitidos son email, teléfono, Slack, Telegram y WhatsApp. El orden importa: el primer método es el que se debe intentar primero. + +### Disponibilidad y brechas de cobertura + +Un contacto está disponible las 24 horas del día (24/7) o disponible durante intervalos semanales que defines, por ejemplo de lunes a viernes, de 09:00 a 17:00. Los intervalos se introducen en la zona horaria local del contacto y se muestran en UTC, por lo que el horario de verano se gestiona automáticamente. + +La vista de **brechas de cobertura** muestra los momentos de cada semana en los que nadie de tu organización está de guardia. Úsala para encontrar y cerrar brechas. + +### Ventanas de rotación + +La semana se divide en ventanas de media hora. Para cada ventana puedes establecer el orden en que se contacta a tus contactos. Esto te permite ejecutar una rotación de guardia sin editar cada contacto. + +### Visibilidad + +Tú controlas quién puede ver tus contactos. DoubleZero siempre puede verlos. Tú eliges quién más puede: + +| Configuración | Quién más puede ver tus contactos | +|---------|-------------------------------| +| Solo DoubleZero (por defecto) | Ningún otro contribuidor | +| Todos | Todos los contribuidores | +| Algunos contribuidores | Solo los contribuidores que selecciones | + +Tu propio equipo siempre puede ver tus contactos. La visibilidad se configura una vez para toda tu organización y se aplica a todos tus contactos. + +--- + +## Gestión de usuarios + +Por defecto, tu clave de Ops Manager es la única cuenta que puede actuar en nombre de tu organización. Puedes añadir miembros del equipo para que más de una persona pueda gestionar tus tickets. + +Abre el menú **Settings** (icono de engranaje) y elige **User Management**. Solo los ops managers pueden añadir o eliminar miembros del equipo. + +Para cada miembro del equipo, establece: + +| Campo | Descripción | +|-------|-------------| +| Nombre | El nombre de la persona | +| Pubkey de wallet | La wallet de Solana con la que inician sesión | +| Nivel de acceso | **Read** o **Read-write** | + +Niveles de acceso: + +- **Read**: puede ver tickets y contactos de escalación, y crear claves API de solo lectura. No puede crear, actualizar ni cerrar tickets. +- **Read-write**: acceso completo para crear, actualizar y cerrar tickets, y puede crear claves API de cualquier nivel. + +Cada miembro del equipo inicia sesión con su propia wallet, de la misma manera que conectaste tu clave de Ops Manager. + +--- + +## Permisos y escalación + +### Qué pueden hacer los contribuidores + +- Crear y gestionar tickets solo para sus propios dispositivos y enlaces. +- Asignar tickets a sí mismos o escalar a DZ/Malbeclabs. +- Ver todos los tickets de todos los contribuidores. +- Añadir miembros del equipo y establecer su nivel de acceso (solo ops managers). +- Gestionar contactos de escalación para su organización (solo ops managers). + +### Qué pueden hacer los administradores de DZ/Malbeclabs + +- Crear tickets para los dispositivos y enlaces de cualquier contribuidor. +- Asignar o reasignar tickets entre contribuidores. +- Gestionar escalaciones y solicitudes de soporte. + +### Propiedad de enlaces DZX + +Los enlaces DZX conectan dispositivos de dos contribuidores diferentes. El contribuidor del **lado A** (primer dispositivo en el nombre del enlace) es el propietario del enlace y es el único que puede crear tickets para él. + +**Ejemplo:** Para el enlace `deviceA:deviceB`, el contribuidor que posee `deviceA` es el propietario del enlace. + +**Si el problema está en el lado Z:** + +1. El contribuidor del lado A crea un ticket para el enlace DZX. +2. Asigna el ticket a DZ/Malbeclabs. +3. DZ/Malbeclabs investiga y reasigna al contribuidor del lado Z si es necesario. + +Reconocemos que este flujo de trabajo es limitado. Los contribuidores del lado Z actualmente no pueden crear tickets para enlaces DZX que no poseen, lo que significa que la coordinación tiene que pasar por DZ/Malbeclabs. Estamos trabajando para mejorar esto de modo que ambos lados de un enlace DZX puedan declarar incidentes y mantenimientos de forma independiente. \ No newline at end of file diff --git a/docs/contribute-ops-management.fr.md b/docs/contribute-ops-management.fr.md new file mode 100644 index 0000000..556680a --- /dev/null +++ b/docs/contribute-ops-management.fr.md @@ -0,0 +1,313 @@ +# Gestion OPS + +Le portail de gestion OPS de DoubleZero est l'endroit où les contributeurs enregistrent et suivent les incidents (pannes imprévues) et les maintenances (travaux planifiés) sur l'ensemble du réseau. Tous les tickets sont visibles par tous les contributeurs. + +**Portail :** [https://doublezero.xyz/ops-management](https://doublezero.xyz/ops-management) + +## Portail vs Slack + +Le portail de gestion OPS et Slack fonctionnent ensemble. Tous les incidents et maintenances sont suivis sous forme de tickets, accessibles via le portail ou l'API. Chaque ticket notifie automatiquement les bons canaux Slack et offre à chaque contributeur une vue partagée de ce qui se passe sur le réseau. Slack est l'endroit où la conversation se déroule : partager des logs, se coordonner avec d'autres contributeurs et collaborer sur les problèmes en cours. + +Les tickets constituent l'enregistrement de référence, qu'ils soient créés via le portail ou l'API. Les fils Slack ne le sont pas : ils ne mettent pas à jour le statut des tickets et ne sont pas stockés de manière permanente. Gardez toujours le statut du ticket à jour, même si la conversation se déroule dans Slack. + +Le portail et Slack servent des objectifs différents. Utilisez les deux, mais pour les bonnes choses. + +| Utilisez le portail (ou l'API) pour... | Utilisez Slack pour... | +|-------------------------------|-----------------| +| Ouvrir, mettre à jour et fermer des tickets | La conversation et la collaboration sur un problème en cours | +| Enregistrer les transitions de statut | Partager des logs, des captures d'écran ou lancer un appel | +| Assigner ou escalader un ticket | Attirer rapidement l'attention sur un problème | +| Définir la cause racine à la clôture | Se coordonner avec d'autres contributeurs | + + + +--- + +## Intégration + +Complétez ces étapes une seule fois avant d'utiliser le portail. + +### 1. Définir votre clé Ops Manager + +Enregistrez une clé publique de portefeuille Solana comme clé Ops Manager. Portefeuilles pris en charge : Phantom, Solflare, Coinbase Wallet. + +```bash +doublezero contributor update \ + --ops-manager \ + --pubkey +``` + +### 2. Connecter votre portefeuille sur le portail + +1. Accédez à [https://doublezero.xyz/ops-management](https://doublezero.xyz/ops-management). +2. Cliquez sur **Connect Your Wallet** et sélectionnez votre portefeuille. +3. Signez le message pour prouver que vous êtes propriétaire de votre clé Ops Manager. + +Une fois authentifié, le **tableau de suivi des incidents** s'affiche. + +Les paramètres du compte se trouvent derrière le menu **Settings** (l'icône d'engrenage, en haut à droite) : gestion des clés API, gestion des utilisateurs et contacts d'escalade. Les options affichées dépendent de votre rôle. + +### 3. Créer des clés API (optionnel) + +Pour un accès programmatique au lieu du formulaire web : + +1. Ouvrez le menu **Settings** (icône d'engrenage) et choisissez **API Key Management**. +2. Créez une ou plusieurs clés API. +3. Téléchargez la documentation de l'API depuis cette page. + +--- + +## Incidents + +Un incident est un événement imprévu impactant le service. + +### Niveaux de sévérité + +Attribuez la sévérité en fonction de l'impact sur le réseau DoubleZero. Vous pouvez mettre à jour la sévérité au fur et à mesure de l'évolution de la situation. + +| Sévérité | Impact | Réponse | +|----------|--------|----------| +| `sev1` | Panne complète ou rupture majeure du plan de contrôle/données sans solution de repli | Tout lâcher immédiatement, même en dehors des heures de travail. Escalader immédiatement à la DoubleZero Foundation. | +| `sev2` | Impact partiel mais substantiel ; service dégradé avec solution de repli possible | Traiter comme urgent. Coordonner activement. Réponse nocturne requise en cas de dégradation prolongée. | +| `sev3` | Impact limité ou non visible par l'utilisateur ; potentiel d'escalade si non résolu | Priorité absolue pendant les heures de travail. Surveiller attentivement. Aucune escalade en dehors des heures requise sauf si l'impact augmente. | + +??? note "Exemples de sévérité" + + **Exemples Sev1** + + - Plus de 10 % du trafic utilisateur perdu (blackholed) sur DoubleZero, sans repli vers l'internet public + - Plus de 80 % des tentatives d'intégration, de connexion ou de déconnexion des utilisateurs en échec + - Plus de 20 % des DZD signalant des erreurs d'interface + - Le contrôleur renvoyant des configurations valides mais incorrectes aux agents DZD + + **Exemples Sev2** + + - Plus de 20 % des utilisateurs incapables d'envoyer/recevoir du trafic via les tunnels DoubleZero, mais avec repli vers l'internet public + - 0 à 10 % du trafic utilisateur perdu (blackholed) sur DoubleZero sans repli + - 20 à 80 % des nouvelles tentatives d'intégration, de connexion ou de déconnexion des utilisateurs en échec + - Plus de 20 % des agents de configuration échouant à appliquer la configuration DZD + - 0 à 20 % des DZD signalant des erreurs d'interface + - Problèmes en amont causant une perte d'observabilité (monitoring/alerting en panne) + - Pipeline de données onchain en panne ou produisant des données incorrectes + - Plus de 20 % de la collecte ou soumission de latence internet en échec + - Contrôleur inaccessible par les agents DZD + - Contrôleur renvoyant des configurations invalides aux DZD qui ne seront pas appliquées + + **Exemples Sev3** + + - 0 à 20 % des utilisateurs incapables d'envoyer/recevoir du trafic via les tunnels DoubleZero, avec repli vers l'internet public + - 0 à 20 % des DZD signalant des erreurs d'interface + - 0 à 20 % des DZD rencontrant des échecs d'agent de configuration + - 0 à 20 % des tentatives d'intégration, de connexion ou de déconnexion des utilisateurs en échec + - Plus de 20 % de la collecte ou soumission de latence internet en échec pour un seul fournisseur de données + - 0 à 20 % de la collecte ou soumission de latence internet en échec pour tous les fournisseurs de données + - Bugs ou dette technique causant du bruit d'alerte qui ne peut pas être réduit au silence + - DIA en panne ou problèmes réseau de ledger RPC pour 0 à 20 % des appareils pendant plusieurs heures + - Problèmes à faible impact tels que bugs mineurs, erreurs cosmétiques ou incidents isolés n'affectant pas le trafic client + - Petite fraction d'appareils signalant des erreurs de manière intermittente sans perturbation du service + +### Ouvrir un incident + +Cliquez sur **Create New Record**, sélectionnez Type = **Incident** sur le portail, ou soumettez via l'API. + +**Requis :** + +| Champ | Description | +|-------|-------------| +| `title` | Résumé court (100 caractères maximum) | +| `description` | Explication détaillée (500 caractères maximum) | +| `severity` | `sev1`, `sev2` ou `sev3` | +| `status` | Ne peut pas être défini à un état terminal (`resolved`, `closed`) à la création | +| Appareil et/ou Lien | Au moins un requis. Sur le formulaire web, sélectionnez depuis un menu déroulant de vos codes d'appareils et de liens. En utilisant l'API, passez les clés publiques correspondantes en tant que `device_pubkey` et/ou `affected_link_pubkey`. | + +**Optionnel :** + +| Champ | Description | +|-------|-------------| +| `reporter_name` / `reporter_email` | Vos coordonnées | +| `assignee` | Qui est responsable de la résolution | +| `internal_reference` | Votre ID de ticket interne (ex. Jira, ServiceNow) | +| `start_at` | Par défaut à l'heure de création ; modifiable | + +Une fois créé, une notification est publiée dans le canal Slack des incidents contributeurs avec l'ID du ticket, la sévérité, les appareils/liens affectés et le nom du contributeur. + +### Mettre à jour un incident + +Au fur et à mesure de l'évolution de l'incident, maintenez le statut du ticket à jour. C'est le signal que les autres contributeurs et DZ utilisent pour comprendre ce qui est en cours de traitement. + +| Statut | Quand le définir | +|--------|----------------| +| `open` | État initial : problème signalé, pas encore en cours de traitement | +| `acknowledged` | Vous l'avez vu et en avez pris la responsabilité | +| `investigating` | Diagnostic actif : collecte de logs, vérification des métriques | +| `mitigating` | Cause racine connue ou suspectée ; application d'un correctif ou d'une solution de contournement | +| `monitoring` | Correctif appliqué ; surveillance pour confirmer qu'il tient | +| `resolved` | Problème confirmé résolu ; **cause racine requise** | +| `closed` | Entièrement terminé ; aucune action supplémentaire ; **cause racine requise** | + +``` +open → acknowledged → investigating → mitigating → monitoring → resolved → closed +``` + +Vous pouvez sauter des statuts si c'est approprié. Par exemple, passer directement de `open` à `investigating` si vous commencez immédiatement à travailler dessus. Utilisez toujours le statut le plus précis pour l'état actuel. + +Chaque mise à jour de statut publie une réponse dans le fil de notification Slack original. + +### Clôturer un incident + +Pour faire passer un incident à `resolved` ou `closed`, une **cause racine** doit être définie. Vous pouvez définir la cause racine à un stade antérieur si vous la connaissez déjà ; elle devient obligatoire à la clôture. + +| Code | Description | +|------|-------------| +| `hardware` | Réparation, remplacement ou mise à niveau matérielle (SFP, NIC, câble, appareil) | +| `software` | Correctif, mise à jour ou redémarrage logiciel ou firmware | +| `configuration` | Changement, correction ou rollback de configuration | +| `capacity` | Congestion, limites de capacité ou gestion du trafic | +| `carrier` | Problème de circuit, longueur d'onde ou fournisseur de cross-connect | +| `network_external` | Problème réseau externe hors du contrôle du contributeur | +| `facility` | Problème d'infrastructure du datacenter (alimentation, refroidissement) | +| `fiber_cut` | Dommage physique de fibre réparé | +| `security` | Incident de sécurité atténué | +| `human_error` | Erreur opérationnelle corrigée | +| `false_positive` | Aucun problème réel trouvé après investigation | +| `duplicate` | Déjà suivi dans un autre ticket | +| `self_resolved` | Problème résolu sans intervention | +| `dz_managed` | Problème avec un composant logiciel géré par DoubleZero (activator, controller, etc.) | + +--- + +## Maintenance + +Un enregistrement de maintenance est une activité planifiée, limitée dans le temps, pouvant affecter la disponibilité. Créez-le à l'avance afin que les autres contributeurs puissent le voir et éviter les fenêtres conflictuelles. + +### Planifier une maintenance + +Cliquez sur **Create New Record** > **Maintenance** sur le portail, ou soumettez via l'API. + +**Requis :** + +| Champ | Description | +|-------|-------------| +| `title` | Résumé court (100 caractères maximum) | +| `description` | Explication détaillée (500 caractères maximum) | +| `start_at` | Heure de début prévue (UTC) | +| `end_at` | Heure de fin prévue (UTC) ; doit être postérieure à `start_at` | +| Appareil et/ou Lien | Au moins un requis. Sur le formulaire web, sélectionnez depuis un menu déroulant de vos codes d'appareils et de liens. En utilisant l'API, passez les clés publiques correspondantes en tant que `device_pubkey` et/ou `affected_link_pubkey`. | + +Une fois créé, une notification est publiée dans le canal Slack de maintenance des contributeurs avec l'ID du ticket, les appareils/liens affectés, la fenêtre prévue et le nom du contributeur. + +### Gérer le statut de maintenance + +Maintenez le statut à jour au fur et à mesure de l'avancement de la fenêtre. + +| Statut | Quand le définir | +|--------|----------------| +| `planned` | Planifié, pas encore commencé | +| `in-progress` | Les travaux ont commencé | +| `completed` | Travaux terminés avec succès | +| `closed` | Défini automatiquement 24 heures après `end_at` | +| `cancelled` | Annulé avant ou pendant l'exécution | + +``` +planned → in-progress → completed → closed (auto 24h après end_at) + ↓ ↓ + └──────────┴──→ cancelled +``` + +--- + +## Contacts d'escalade + +Les contacts d'escalade indiquent à DoubleZero et aux autres contributeurs qui contacter lorsque votre partie du réseau rencontre un problème. Vous configurez vos propres contacts pour votre organisation. Un contact peut être une personne ou une équipe, comme votre NOC. Chaque contact dispose d'un ou plusieurs moyens de le joindre et d'un planning indiquant quand il est d'astreinte. + +Ouvrez le menu **Settings** (icône d'engrenage) et choisissez **Escalation Contacts**. Seuls les ops managers peuvent ajouter ou modifier des contacts. + +### Ajouter un contact + +Pour chaque contact, définissez : + +| Champ | Description | +|-------|-------------| +| Nom | Un nom pour le contact, qu'il s'agisse d'une personne ou d'une équipe comme votre NOC | +| Fuseau horaire | Le fuseau horaire local, utilisé pour lire le planning | +| Disponibilité | **24/7**, ou un ou plusieurs créneaux hebdomadaires pendant lesquels le contact est d'astreinte | +| Méthodes de contact | Un ou plusieurs moyens de joindre le contact, par ordre de priorité | + +Les méthodes de contact prises en charge sont l'email, le téléphone, Slack, Telegram et WhatsApp. L'ordre est important : la première méthode est celle à essayer en premier. + +### Disponibilité et lacunes de couverture + +Un contact est soit disponible en permanence (24/7), soit disponible pendant des créneaux hebdomadaires que vous définissez, par exemple du lundi au vendredi, de 09h00 à 17h00. Les créneaux sont saisis dans le fuseau horaire local du contact et affichés en UTC, de sorte que l'heure d'été est gérée pour vous. + +La vue **lacunes de couverture** montre les moments de chaque semaine où personne de votre organisation n'est d'astreinte. Utilisez-la pour identifier et combler les lacunes. + +### Fenêtres de rotation + +La semaine est divisée en créneaux de trente minutes. Pour chaque créneau, vous pouvez définir l'ordre dans lequel vos contacts sont sollicités. Cela vous permet de gérer une rotation d'astreinte sans modifier chaque contact individuellement. + +### Visibilité + +Vous contrôlez qui peut voir vos contacts. DoubleZero peut toujours les voir. Vous choisissez qui d'autre peut : + +| Paramètre | Qui d'autre peut voir vos contacts | +|---------|-------------------------------| +| DoubleZero uniquement (par défaut) | Aucun autre contributeur | +| Tout le monde | Tous les contributeurs | +| Certains contributeurs | Uniquement les contributeurs que vous sélectionnez | + +Votre propre équipe peut toujours voir vos contacts. La visibilité est définie une seule fois pour l'ensemble de votre organisation et s'applique à tous vos contacts. + +--- + +## Gestion des utilisateurs + +Par défaut, votre clé Ops Manager est le seul compte pouvant agir au nom de votre organisation. Vous pouvez ajouter des membres d'équipe afin que plusieurs personnes puissent gérer vos tickets. + +Ouvrez le menu **Settings** (icône d'engrenage) et choisissez **User Management**. Seuls les ops managers peuvent ajouter ou supprimer des membres d'équipe. + +Pour chaque membre d'équipe, définissez : + +| Champ | Description | +|-------|-------------| +| Nom | Le nom de la personne | +| Clé publique du portefeuille | Le portefeuille Solana avec lequel elle se connecte | +| Niveau d'accès | **Lecture** ou **Lecture-écriture** | + +Niveaux d'accès : + +- **Lecture** : peut consulter les tickets et les contacts d'escalade, et créer des clés API en lecture seule. Ne peut pas créer, mettre à jour ou fermer des tickets. +- **Lecture-écriture** : accès complet pour créer, mettre à jour et fermer des tickets, et peut créer des clés API de tout niveau. + +Chaque membre d'équipe se connecte avec son propre portefeuille, de la même manière que vous avez connecté votre clé Ops Manager. + +--- + +## Permissions et escalade + +### Ce que les contributeurs peuvent faire + +- Créer et gérer des tickets pour leurs propres appareils et liens uniquement. +- S'assigner des tickets ou escalader vers DZ/Malbeclabs. +- Voir tous les tickets de tous les contributeurs. +- Ajouter des membres d'équipe et définir leur niveau d'accès (ops managers uniquement). +- Gérer les contacts d'escalade pour leur organisation (ops managers uniquement). + +### Ce que les administrateurs DZ/Malbeclabs peuvent faire + +- Créer des tickets pour les appareils et liens de n'importe quel contributeur. +- Assigner ou réassigner des tickets entre contributeurs. +- Traiter les escalades et les demandes de support. + +### Propriété des liens DZX + +Les liens DZX connectent des appareils de deux contributeurs différents. Le contributeur **côté A** (premier appareil dans le nom du lien) est propriétaire du lien et est le seul à pouvoir créer des tickets pour celui-ci. + +**Exemple :** Pour le lien `deviceA:deviceB`, le contributeur propriétaire de `deviceA` est propriétaire du lien. + +**Si le problème est côté Z :** + +1. Le contributeur côté A crée un ticket pour le lien DZX. +2. Assigne le ticket à DZ/Malbeclabs. +3. DZ/Malbeclabs enquête et réassigne au contributeur côté Z si nécessaire. + +Nous reconnaissons que ce workflow est limité. Les contributeurs côté Z ne peuvent actuellement pas créer de tickets pour les liens DZX dont ils ne sont pas propriétaires, ce qui signifie que la coordination doit passer par DZ/Malbeclabs. Nous travaillons à améliorer cela afin que les deux côtés d'un lien DZX puissent déclarer des incidents et des maintenances de manière indépendante. \ No newline at end of file diff --git a/docs/contribute-ops-management.it.md b/docs/contribute-ops-management.it.md new file mode 100644 index 0000000..22577c7 --- /dev/null +++ b/docs/contribute-ops-management.it.md @@ -0,0 +1,313 @@ +# Gestione OPS + +Il portale di gestione OPS di DoubleZero è il luogo in cui i contributor registrano e tracciano gli incidenti (interruzioni non pianificate) e le manutenzioni (lavori pianificati) su tutta la rete. Tutti i ticket sono visibili a tutti i contributor. + +**Portale:** [https://doublezero.xyz/ops-management](https://doublezero.xyz/ops-management) + +## Portale vs Slack + +Il portale di gestione OPS e Slack funzionano insieme. Tutti gli incidenti e le manutenzioni vengono tracciati come ticket, accessibili tramite il portale o l'API. Ogni ticket notifica automaticamente i canali Slack appropriati e offre a ogni contributor una visione condivisa di ciò che sta accadendo sulla rete. Slack è il luogo in cui avviene la conversazione: condivisione di log, coordinamento con altri contributor e collaborazione su problemi attivi. + +I ticket sono il registro ufficiale, sia che vengano creati tramite il portale o l'API. I thread di Slack no: non aggiornano lo stato del ticket e non vengono archiviati permanentemente. Mantieni sempre aggiornato lo stato del ticket, anche se la conversazione avviene su Slack. + +Il portale e Slack servono a scopi diversi. Usa entrambi, ma per le cose giuste. + +| Usa il portale (o l'API) per... | Usa Slack per... | +|-------------------------------|-----------------| +| Aprire, aggiornare e chiudere ticket | Conversazione e collaborazione su un problema attivo | +| Registrare le transizioni di stato | Condividere log, screenshot o avviare una chiamata | +| Assegnare o escalare un ticket | Attirare rapidamente l'attenzione su un problema | +| Impostare la causa radice alla chiusura | Coordinarsi con altri contributor | + + + +--- + +## Onboarding + +Completa questi passaggi una volta prima di utilizzare il portale. + +### 1. Imposta la tua chiave Ops Manager + +Registra una pubkey di un wallet Solana come chiave Ops Manager. Wallet supportati: Phantom, Solflare, Coinbase Wallet. + +```bash +doublezero contributor update \ + --ops-manager \ + --pubkey +``` + +### 2. Collega il tuo wallet sul portale + +1. Vai su [https://doublezero.xyz/ops-management](https://doublezero.xyz/ops-management). +2. Clicca su **Connect Your Wallet** e seleziona il tuo wallet. +3. Firma il messaggio per dimostrare la proprietà della tua chiave Ops Manager. + +Una volta autenticato, viene mostrata la **Tabella di Tracciamento Incidenti**. + +Le impostazioni dell'account si trovano nel menu **Settings** (l'icona a ingranaggio, in alto a destra): API Key Management, User Management e Escalation Contacts. Le opzioni visibili dipendono dal tuo ruolo. + +### 3. Crea chiavi API (Opzionale) + +Per l'accesso programmatico in alternativa al modulo web: + +1. Apri il menu **Settings** (icona a ingranaggio) e scegli **API Key Management**. +2. Crea una o più chiavi API. +3. Scarica la documentazione API da questa pagina. + +--- + +## Incidenti + +Un incidente è un evento non pianificato che impatta il servizio. + +### Livelli di Severità + +Assegna la severità in base all'impatto sulla rete DoubleZero. Puoi aggiornare la severità man mano che la situazione evolve. + +| Severità | Impatto | Risposta | +|----------|---------|----------| +| `sev1` | Interruzione totale o grave malfunzionamento del piano di controllo/dati senza fallback | Lascia tutto immediatamente, anche fuori dall'orario di lavoro. Escala immediatamente alla DoubleZero Foundation. | +| `sev2` | Impatto parziale ma sostanziale; servizio degradato con possibile fallback | Tratta come urgente. Coordinati attivamente. Risposta notturna richiesta per degradazioni prolungate. | +| `sev3` | Impatto limitato o non visibile agli utenti; potenziale escalation se non risolto | Massima priorità durante l'orario di lavoro. Monitora attentamente. Nessuna escalation fuori orario richiesta a meno che l'impatto non aumenti. | + +??? note "Esempi di severità" + + **Esempi Sev1** + + - Più del 10% del traffico utente perso su DoubleZero, nessun fallback verso internet pubblico + - Più dell'80% dei tentativi di onboarding, connessione o disconnessione degli utenti falliti + - Più del 20% dei DZD che riportano errori di interfaccia + - Il controller restituisce configurazioni valide ma errate agli agenti DZD + + **Esempi Sev2** + + - Più del 20% degli utenti impossibilitati a inviare/ricevere traffico sui tunnel DoubleZero, ma con fallback verso internet pubblico + - 0–10% del traffico utente perso su DoubleZero senza fallback + - 20–80% dei nuovi tentativi di onboarding, connessione o disconnessione degli utenti falliti + - Più del 20% degli agenti di configurazione che non riescono ad applicare la configurazione DZD + - 0–20% dei DZD che riportano errori di interfaccia + - Problemi upstream che causano perdita di osservabilità (monitoraggio/alerting non funzionanti) + - Pipeline dati onchain non funzionante o che produce dati errati + - Più del 20% della raccolta o invio di latenza internet falliti + - Controller irraggiungibile dagli agenti DZD + - Controller che restituisce configurazioni non valide ai DZD che non verranno applicate + + **Esempi Sev3** + + - 0–20% degli utenti impossibilitati a inviare/ricevere traffico sui tunnel DoubleZero, con fallback verso internet pubblico + - 0–20% dei DZD che riportano errori di interfaccia + - 0–20% dei DZD che riscontrano errori dell'agente di configurazione + - 0–20% dei tentativi di onboarding, connessione o disconnessione degli utenti falliti + - Più del 20% della raccolta o invio di latenza internet falliti per un singolo fornitore di dati + - 0–20% della raccolta o invio di latenza internet falliti per tutti i fornitori di dati + - Bug o debito tecnico che causa rumore negli alert che non può essere silenziato + - DIA non funzionante o problemi di rete RPC del ledger per 0–20% dei dispositivi per diverse ore + - Problemi a basso impatto come bug minori, errori estetici o incidenti isolati che non impattano il traffico dei clienti + - Piccola frazione di dispositivi che riportano errori intermittenti senza interruzione del servizio + +### Apertura di un Incidente + +Clicca su **Create New Record**, seleziona Type = **Incident** sul portale, oppure invia tramite l'API. + +**Obbligatori:** + +| Campo | Descrizione | +|-------|-------------| +| `title` | Breve riepilogo (max 100 caratteri) | +| `description` | Spiegazione dettagliata (max 500 caratteri) | +| `severity` | `sev1`, `sev2` o `sev3` | +| `status` | Non può essere impostato su uno stato terminale (`resolved`, `closed`) alla creazione | +| Dispositivo e/o Link | Almeno uno obbligatorio. Nel modulo web, seleziona dal menu a tendina dei codici dei tuoi dispositivi e link. Quando usi l'API, passa le pubkey corrispondenti come `device_pubkey` e/o `affected_link_pubkey`. | + +**Opzionali:** + +| Campo | Descrizione | +|-------|-------------| +| `reporter_name` / `reporter_email` | I tuoi recapiti | +| `assignee` | Chi è responsabile della risoluzione | +| `internal_reference` | Il tuo ID ticket interno (es. Jira, ServiceNow) | +| `start_at` | Default all'ora di creazione; modificabile | + +Una volta creato, una notifica viene pubblicata nel canale Slack per gli incidenti dei contributor con l'ID del ticket, la severità, i dispositivi/link interessati e il nome del contributor. + +### Aggiornamento di un Incidente + +Man mano che l'incidente progredisce, mantieni aggiornato lo stato del ticket. Questo è il segnale che altri contributor e DZ usano per capire su cosa si sta lavorando. + +| Stato | Quando impostarlo | +|-------|-------------------| +| `open` | Stato iniziale: problema segnalato, non ancora in lavorazione | +| `acknowledged` | L'hai visto e te ne sei preso carico | +| `investigating` | Diagnosi attiva: raccolta log, verifica metriche | +| `mitigating` | Causa radice nota o sospettata; applicazione di una correzione o workaround | +| `monitoring` | Correzione applicata; monitoraggio per confermare che tiene | +| `resolved` | Problema confermato come risolto; **causa radice obbligatoria** | +| `closed` | Completamente concluso; nessuna ulteriore azione; **causa radice obbligatoria** | + +``` +open → acknowledged → investigating → mitigating → monitoring → resolved → closed +``` + +Puoi saltare degli stati se appropriato. Ad esempio, passa direttamente da `open` a `investigating` se inizi a lavorarci immediatamente. Usa sempre lo stato più accurato per la situazione corrente. + +Ogni aggiornamento di stato pubblica una risposta nel thread della notifica Slack originale. + +### Chiusura di un Incidente + +Per portare un incidente allo stato `resolved` o `closed`, è necessario impostare una **causa radice**. Puoi impostare la causa radice in qualsiasi fase precedente se la conosci già; diventa obbligatoria alla chiusura. + +| Codice | Descrizione | +|--------|-------------| +| `hardware` | Riparazione, sostituzione o aggiornamento hardware (SFP, NIC, cavo, dispositivo) | +| `software` | Correzione, aggiornamento o riavvio software o firmware | +| `configuration` | Modifica, correzione o rollback della configurazione | +| `capacity` | Congestione, limiti di capacità o gestione del traffico | +| `carrier` | Problema del fornitore di circuito, lunghezza d'onda o cross-connect | +| `network_external` | Problema di rete esterno al di fuori del controllo del contributor | +| `facility` | Problema dell'infrastruttura del datacenter (alimentazione, raffreddamento) | +| `fiber_cut` | Danno fisico alla fibra riparato | +| `security` | Incidente di sicurezza mitigato | +| `human_error` | Errore operativo corretto | +| `false_positive` | Nessun problema reale trovato dopo l'indagine | +| `duplicate` | Già tracciato in un altro ticket | +| `self_resolved` | Problema risolto senza intervento | +| `dz_managed` | Problema con un componente software gestito da DoubleZero (activator, controller, ecc.) | + +--- + +## Manutenzione + +Un record di manutenzione è un'attività pianificata e delimitata nel tempo che potrebbe influire sulla disponibilità. Crealo in anticipo così che altri contributor possano vederlo ed evitare finestre in conflitto. + +### Pianificazione della Manutenzione + +Clicca su **Create New Record** > **Maintenance** sul portale, oppure invia tramite l'API. + +**Obbligatori:** + +| Campo | Descrizione | +|-------|-------------| +| `title` | Breve riepilogo (max 100 caratteri) | +| `description` | Spiegazione dettagliata (max 500 caratteri) | +| `start_at` | Orario di inizio pianificato (UTC) | +| `end_at` | Orario di fine pianificato (UTC); deve essere successivo a `start_at` | +| Dispositivo e/o Link | Almeno uno obbligatorio. Nel modulo web, seleziona dal menu a tendina dei codici dei tuoi dispositivi e link. Quando usi l'API, passa le pubkey corrispondenti come `device_pubkey` e/o `affected_link_pubkey`. | + +Una volta creato, una notifica viene pubblicata nel canale Slack per le manutenzioni dei contributor con l'ID del ticket, i dispositivi/link interessati, la finestra pianificata e il nome del contributor. + +### Gestione dello Stato della Manutenzione + +Mantieni aggiornato lo stato man mano che la finestra progredisce. + +| Stato | Quando impostarlo | +|-------|-------------------| +| `planned` | Pianificata, non ancora iniziata | +| `in-progress` | Il lavoro è iniziato | +| `completed` | Lavoro terminato con successo | +| `closed` | Impostato automaticamente 24 ore dopo `end_at` | +| `cancelled` | Annullata prima o durante l'esecuzione | + +``` +planned → in-progress → completed → closed (auto 24h after end_at) + ↓ ↓ + └──────────┴──→ cancelled +``` + +--- + +## Contatti di Escalation + +I contatti di escalation indicano a DoubleZero e agli altri contributor chi contattare quando la tua parte della rete ha un problema. Configuri i tuoi contatti per la tua organizzazione. Un contatto può essere una persona o un team, come il tuo NOC. Ogni contatto ha uno o più modi per essere raggiunto e un orario di reperibilità. + +Apri il menu **Settings** (icona a ingranaggio) e scegli **Escalation Contacts**. Solo gli ops manager possono aggiungere o modificare i contatti. + +### Aggiunta di un Contatto + +Per ogni contatto, imposta: + +| Campo | Descrizione | +|-------|-------------| +| Name | Un nome per il contatto, sia esso una persona o un team come il tuo NOC | +| Timezone | Il fuso orario locale, utilizzato per leggere l'orario | +| Availability | **24/7**, oppure una o più fasce orarie settimanali in cui il contatto è reperibile | +| Contact methods | Uno o più modi per raggiungere il contatto, in ordine di priorità | + +I metodi di contatto supportati sono email, telefono, Slack, Telegram e WhatsApp. L'ordine è importante: il primo metodo è quello da provare per primo. + +### Disponibilità e Gap di Copertura + +Un contatto è disponibile 24 ore su 24, 7 giorni su 7, oppure durante fasce orarie settimanali che definisci, ad esempio dal lunedì al venerdì, dalle 09:00 alle 17:00. Le fasce vengono inserite nel fuso orario locale del contatto e visualizzate in UTC, quindi l'ora legale viene gestita automaticamente. + +La vista **coverage gaps** mostra i momenti della settimana in cui nessuno della tua organizzazione è reperibile. Usala per individuare e colmare i gap. + +### Finestre di Rotazione + +La settimana è suddivisa in finestre di mezz'ora. Per ogni finestra puoi impostare l'ordine in cui i tuoi contatti vengono raggiunti. Questo ti permette di gestire una rotazione di reperibilità senza modificare ogni singolo contatto. + +### Visibilità + +Controlli chi può vedere i tuoi contatti. DoubleZero può sempre vederli. Tu scegli chi altro può: + +| Impostazione | Chi altro può vedere i tuoi contatti | +|--------------|--------------------------------------| +| Solo DoubleZero (predefinito) | Nessun altro contributor | +| Tutti | Tutti i contributor | +| Alcuni contributor | Solo i contributor che selezioni | + +Il tuo team può sempre vedere i tuoi contatti. La visibilità viene impostata una volta per tutta la tua organizzazione e si applica a tutti i tuoi contatti. + +--- + +## Gestione Utenti + +Per impostazione predefinita, la tua chiave Ops Manager è l'unico account che può agire per la tua organizzazione. Puoi aggiungere membri del team in modo che più di una persona possa gestire i tuoi ticket. + +Apri il menu **Settings** (icona a ingranaggio) e scegli **User Management**. Solo gli ops manager possono aggiungere o rimuovere membri del team. + +Per ogni membro del team, imposta: + +| Campo | Descrizione | +|-------|-------------| +| Name | Il nome della persona | +| Wallet pubkey | Il wallet Solana con cui effettua l'accesso | +| Access level | **Read** o **Read-write** | + +Livelli di accesso: + +- **Read**: può visualizzare ticket e contatti di escalation e creare chiavi API di sola lettura. Non può creare, aggiornare o chiudere ticket. +- **Read-write**: accesso completo per creare, aggiornare e chiudere ticket, e può creare chiavi API di qualsiasi livello. + +Ogni membro del team accede con il proprio wallet, nello stesso modo in cui hai collegato la tua chiave Ops Manager. + +--- + +## Permessi ed Escalation + +### Cosa possono fare i Contributor + +- Creare e gestire ticket solo per i propri dispositivi e link. +- Assegnare ticket a se stessi o escalare a DZ/Malbeclabs. +- Visualizzare tutti i ticket di tutti i contributor. +- Aggiungere membri del team e impostare il loro livello di accesso (solo ops manager). +- Gestire i contatti di escalation per la propria organizzazione (solo ops manager). + +### Cosa possono fare gli Admin DZ/Malbeclabs + +- Creare ticket per i dispositivi e link di qualsiasi contributor. +- Assegnare o riassegnare ticket tra contributor. +- Gestire escalation e richieste di supporto. + +### Proprietà dei Link DZX + +I link DZX collegano dispositivi di due contributor diversi. Il contributor **A-side** (primo dispositivo nel nome del link) è il proprietario del link ed è l'unico che può creare ticket per esso. + +**Esempio:** Per il link `deviceA:deviceB`, il contributor che possiede `deviceA` è il proprietario del link. + +**Se il problema è sul lato Z:** + +1. Il contributor A-side crea un ticket per il link DZX. +2. Assegna il ticket a DZ/Malbeclabs. +3. DZ/Malbeclabs indaga e riassegna al contributor Z-side se necessario. + +Riconosciamo che questo flusso di lavoro è limitato. I contributor Z-side attualmente non possono creare ticket per link DZX di cui non sono proprietari, il che significa che il coordinamento deve passare attraverso DZ/Malbeclabs. Stiamo lavorando per migliorare questa situazione in modo che entrambi i lati di un link DZX possano dichiarare incidenti e manutenzioni in modo indipendente. \ No newline at end of file diff --git a/docs/contribute-ops-management.ja.md b/docs/contribute-ops-management.ja.md new file mode 100644 index 0000000..8f24e7e --- /dev/null +++ b/docs/contribute-ops-management.ja.md @@ -0,0 +1,313 @@ +# OPS管理 + +DoubleZero OPS管理ポータルは、コントリビューターがネットワーク全体のインシデント（計画外の障害）とメンテナンス（計画作業）を記録・追跡する場所です。すべてのチケットはすべてのコントリビューターに公開されます。 + +**ポータル:** [https://doublezero.xyz/ops-management](https://doublezero.xyz/ops-management) + +## ポータルとSlack + +OPS管理ポータルとSlackは連携して機能します。すべてのインシデントとメンテナンスはチケットとして追跡され、ポータルまたはAPIからアクセスできます。各チケットは適切なSlackチャンネルに自動的に通知を送り、すべてのコントリビューターにネットワーク上で何が起きているかの共有ビューを提供します。Slackは会話が行われる場所です：ログの共有、他のコントリビューターとの調整、アクティブな問題に関するコラボレーションなど。 + +チケットは、ポータル経由で作成されたものもAPI経由で作成されたものも、正式な記録です。Slackスレッドはそうではありません：チケットのステータスを更新せず、永続的に保存されることもありません。会話がSlackで行われている場合でも、チケットのステータスを常に最新の状態に保ってください。 + +ポータルとSlackはそれぞれ異なる目的を持っています。両方を使用してください。ただし、適切な用途に使い分けてください。 + +| ポータル（またはAPI）で行うこと... | Slackで行うこと... | +|-------------------------------|-----------------| +| チケットのオープン、更新、クローズ | アクティブな問題に関する会話とコラボレーション | +| ステータス遷移の記録 | ログやスクリーンショットの共有、通話の開始 | +| チケットの割り当てまたはエスカレーション | 問題に素早く注目を集める | +| クローズ時の根本原因の設定 | 他のコントリビューターとの調整 | + + + +--- + +## オンボーディング + +ポータルを使用する前に、以下の手順を一度完了してください。 + +### 1. Ops Managerキーの設定 + +SolanaウォレットのpubkeyをOps Managerキーとして登録します。対応ウォレット：Phantom、Solflare、Coinbase Wallet。 + +```bash +doublezero contributor update \ + --ops-manager \ + --pubkey +``` + +### 2. ポータルでウォレットを接続 + +1. [https://doublezero.xyz/ops-management](https://doublezero.xyz/ops-management) にアクセスします。 +2. **Connect Your Wallet** をクリックし、ウォレットを選択します。 +3. Ops Managerキーの所有権を証明するためにメッセージに署名します。 + +認証が完了すると、**Incident Tracking Table** が表示されます。 + +アカウント設定は **Settings** メニュー（右上の歯車アイコン）にあります：API Key Management、User Management、Escalation Contacts。表示されるオプションはロールによって異なります。 + +### 3. APIキーの作成（オプション） + +Webフォームの代わりにプログラムでアクセスする場合： + +1. **Settings** メニュー（歯車アイコン）を開き、**API Key Management** を選択します。 +2. 1つ以上のAPIキーを作成します。 +3. このページからAPIドキュメントをダウンロードします。 + +--- + +## インシデント + +インシデントとは、計画外のサービスに影響を与えるイベントです。 + +### 重大度レベル + +DoubleZeroネットワークへの影響に基づいて重大度を割り当てます。状況の変化に応じて重大度を更新できます。 + +| 重大度 | 影響 | 対応 | +|----------|--------|----------| +| `sev1` | フォールバックなしの完全な障害、または重大なコントロール/データプレーンの障害 | 勤務時間外であっても、直ちにすべてを中断して対応。DoubleZero Foundationに即座にエスカレーション。 | +| `sev2` | 部分的だが大きな影響；フォールバックの可能性があるサービス劣化 | 緊急として対応。積極的に調整。持続的な劣化に対しては夜間対応も必要。 | +| `sev3` | ユーザーへの影響が限定的またはなし；未解決の場合はエスカレーションの可能性あり | 勤務時間中の最優先事項。注意深く監視。影響が増大しない限り、時間外のエスカレーションは不要。 | + +??? note "重大度の例" + + **Sev1の例** + + - DoubleZero上のユーザートラフィックの10%以上がブラックホール化、公衆インターネットへのフォールバックなし + - ユーザーのオンボーディング、接続、または切断の試行の80%以上が失敗 + - DZDの20%以上がインターフェースエラーを報告 + - コントローラーがDZDエージェントに有効だが不正な設定を返している + + **Sev2の例** + + - ユーザーの20%以上がDoubleZeroトンネル経由でトラフィックを送受信できないが、公衆インターネットにフォールバック中 + - DoubleZero上のユーザートラフィックの0〜10%がフォールバックなしでブラックホール化 + - 新規ユーザーのオンボーディング、接続、または切断の試行の20〜80%が失敗 + - 設定エージェントの20%以上がDZD設定の適用に失敗 + - DZDの0〜20%がインターフェースエラーを報告 + - 上流の問題によるオブザーバビリティの喪失（監視/アラートがダウン） + - オンチェーンデータパイプラインがダウンまたは不正なデータを生成 + - インターネットレイテンシの収集または送信の20%以上が失敗 + - DZDエージェントがコントローラーにアクセスできない + - コントローラーがDZDに対して適用されない無効な設定を返している + + **Sev3の例** + + - ユーザーの0〜20%がDoubleZeroトンネル経由でトラフィックを送受信できないが、公衆インターネットにフォールバック可能 + - DZDの0〜20%がインターフェースエラーを報告 + - DZDの0〜20%が設定エージェントの障害を経験 + - ユーザーのオンボーディング、接続、または切断の試行の0〜20%が失敗 + - 単一のデータプロバイダーにおけるインターネットレイテンシの収集または送信の20%以上が失敗 + - すべてのデータプロバイダーにおけるインターネットレイテンシの収集または送信の0〜20%が失敗 + - サイレンスにできないアラートノイズを引き起こすバグまたは技術的負債 + - デバイスの0〜20%でDIAがダウンまたはレジャーRPCネットワーキングの問題が数時間発生 + - 軽微なバグ、外観上のエラー、顧客トラフィックに影響しない孤立したインシデントなどの低影響の問題 + - サービス中断なしにごく一部のデバイスが断続的にエラーを報告 + +### インシデントのオープン + +ポータルで **Create New Record** をクリックし、Type = **Incident** を選択するか、API経由で送信します。 + +**必須：** + +| フィールド | 説明 | +|-------|-------------| +| `title` | 短い概要（最大100文字） | +| `description` | 詳細な説明（最大500文字） | +| `severity` | `sev1`、`sev2`、または `sev3` | +| `status` | 作成時に終了ステータス（`resolved`、`closed`）には設定できません | +| デバイスおよび/またはリンク | 少なくとも1つ必要。Webフォームでは、デバイスコードとリンクコードのドロップダウンから選択します。API使用時は、対応するpubkeyを `device_pubkey` および/または `affected_link_pubkey` として渡します。 | + +**オプション：** + +| フィールド | 説明 | +|-------|-------------| +| `reporter_name` / `reporter_email` | 連絡先情報 | +| `assignee` | 解決の責任者 | +| `internal_reference` | 内部チケットID（例：Jira、ServiceNow） | +| `start_at` | デフォルトは作成時刻；編集可能 | + +作成されると、チケットID、重大度、影響を受けるデバイス/リンク、コントリビューター名を含む通知がコントリビューターインシデントSlackチャンネルに投稿されます。 + +### インシデントの更新 + +インシデントの進行に伴い、チケットのステータスを最新の状態に保ってください。これは、他のコントリビューターとDZが何が対応中であるかを理解するためのシグナルです。 + +| ステータス | 設定するタイミング | +|--------|----------------| +| `open` | 初期状態：問題が報告されたが、まだ対応されていない | +| `acknowledged` | 確認し、対応を引き受けた | +| `investigating` | 積極的に診断中：ログの収集、メトリクスの確認 | +| `mitigating` | 根本原因が判明または推測された；修正またはワークアラウンドを適用中 | +| `monitoring` | 修正を適用済み；それが持続するか監視中 | +| `resolved` | 問題の修正を確認済み；**根本原因が必須** | +| `closed` | 完全に完了；追加のアクション不要；**根本原因が必須** | + +``` +open → acknowledged → investigating → mitigating → monitoring → resolved → closed +``` + +適切であればステータスをスキップできます。例えば、すぐに作業を開始した場合は `open` から直接 `investigating` に移行できます。現在の状態に最も正確なステータスを常に使用してください。 + +各ステータス更新は、元のSlack通知スレッドにリプライとして投稿されます。 + +### インシデントのクローズ + +インシデントを `resolved` または `closed` に移行するには、**根本原因**を設定する必要があります。根本原因がすでに判明している場合は、それ以前のステージで設定できます。クローズ時には必須となります。 + +| コード | 説明 | +|------|-------------| +| `hardware` | ハードウェアの修理、交換、またはアップグレード（SFP、NIC、ケーブル、デバイス） | +| `software` | ソフトウェアまたはファームウェアの修正、更新、または再起動 | +| `configuration` | 設定の変更、修正、またはロールバック | +| `capacity` | 輻輳、容量制限、またはトラフィック管理 | +| `carrier` | 回線、波長、またはクロスコネクトプロバイダーの問題 | +| `network_external` | コントリビューターの管理外にある外部ネットワークの問題 | +| `facility` | データセンターインフラの問題（電源、冷却） | +| `fiber_cut` | 物理的な光ファイバー損傷の修復 | +| `security` | セキュリティインシデントの緩和 | +| `human_error` | 運用上のミスの修正 | +| `false_positive` | 調査後に実際の問題は見つからなかった | +| `duplicate` | 別のチケットで既に追跡されている | +| `self_resolved` | 介入なしに問題が解決した | +| `dz_managed` | DoubleZeroが管理するソフトウェアコンポーネント（activator、controllerなど）の問題 | + +--- + +## メンテナンス + +メンテナンスレコードは、可用性に影響を与える可能性のある計画的で期間が定められた作業です。他のコントリビューターが確認し、競合するウィンドウを回避できるように、事前に作成してください。 + +### メンテナンスのスケジューリング + +ポータルで **Create New Record** > **Maintenance** をクリックするか、API経由で送信します。 + +**必須：** + +| フィールド | 説明 | +|-------|-------------| +| `title` | 短い概要（最大100文字） | +| `description` | 詳細な説明（最大500文字） | +| `start_at` | 計画開始時刻（UTC） | +| `end_at` | 計画終了時刻（UTC）；`start_at` より後でなければならない | +| デバイスおよび/またはリンク | 少なくとも1つ必要。Webフォームでは、デバイスコードとリンクコードのドロップダウンから選択します。API使用時は、対応するpubkeyを `device_pubkey` および/または `affected_link_pubkey` として渡します。 | + +作成されると、チケットID、影響を受けるデバイス/リンク、計画ウィンドウ、コントリビューター名を含む通知がコントリビューターメンテナンスSlackチャンネルに投稿されます。 + +### メンテナンスステータスの管理 + +ウィンドウの進行に伴い、ステータスを最新の状態に保ってください。 + +| ステータス | 設定するタイミング | +|--------|----------------| +| `planned` | スケジュール済み、まだ開始していない | +| `in-progress` | 作業が開始された | +| `completed` | 作業が正常に完了した | +| `closed` | `end_at` の24時間後に自動設定 | +| `cancelled` | 実行前または実行中にキャンセルされた | + +``` +planned → in-progress → completed → closed (end_atの24時間後に自動) + ↓ ↓ + └──────────┴──→ cancelled +``` + +--- + +## エスカレーション連絡先 + +エスカレーション連絡先は、ネットワークのあなたの担当部分に問題が発生した際に、DoubleZeroや他のコントリビューターが誰に連絡すればよいかを示します。自分の組織の連絡先は自分で設定します。連絡先は個人でもチーム（NOCなど）でもかまいません。各連絡先には1つ以上の連絡方法と、オンコールのスケジュールがあります。 + +**Settings** メニュー（歯車アイコン）を開き、**Escalation Contacts** を選択します。連絡先の追加や編集ができるのはops managerのみです。 + +### 連絡先の追加 + +各連絡先に対して、以下を設定します： + +| フィールド | 説明 | +|-------|-------------| +| Name | 連絡先の名前。個人でもNOCなどのチームでも可 | +| Timezone | ローカルタイムゾーン。スケジュールの読み取りに使用 | +| Availability | **24/7**、または連絡先がオンコールである1つ以上の週次タイムスロット | +| Contact methods | 連絡先に到達するための1つ以上の方法。優先順位順 | + +サポートされている連絡方法は、メール、電話、Slack、Telegram、WhatsAppです。順序は重要です：最初の方法が最初に試されます。 + +### 可用性とカバレッジギャップ + +連絡先は、24時間365日（24/7）利用可能であるか、定義した週次タイムスロット（例：月曜日〜金曜日、09:00〜17:00）の間に利用可能です。スロットは連絡先のローカルタイムゾーンで入力され、UTCで表示されるため、夏時間は自動的に処理されます。 + +**カバレッジギャップ**ビューには、組織から誰もオンコールでない毎週の時間帯が表示されます。ギャップを見つけて埋めるために使用してください。 + +### ローテーションウィンドウ + +1週間は30分のウィンドウに分割されます。各ウィンドウに対して、連絡先に到達する順序を設定できます。これにより、各連絡先を編集することなくオンコールローテーションを実行できます。 + +### 表示設定 + +連絡先を誰が見られるかを制御できます。DoubleZeroは常に見ることができます。他に誰が見られるかを選択します： + +| 設定 | 連絡先を見られる他の対象 | +|---------|-------------------------------| +| DoubleZeroのみ（デフォルト） | 他のコントリビューターなし | +| 全員 | すべてのコントリビューター | +| 一部のコントリビューター | 選択したコントリビューターのみ | + +自分のチームは常に連絡先を見ることができます。表示設定は組織全体に対して一度設定され、すべての連絡先に適用されます。 + +--- + +## ユーザー管理 + +デフォルトでは、Ops Managerキーが組織を代表して操作できる唯一のアカウントです。チームメンバーを追加して、複数の人がチケットを管理できるようにできます。 + +**Settings** メニュー（歯車アイコン）を開き、**User Management** を選択します。チームメンバーの追加や削除ができるのはops managerのみです。 + +各チームメンバーに対して、以下を設定します： + +| フィールド | 説明 | +|-------|-------------| +| Name | メンバーの名前 | +| Wallet pubkey | サインインに使用するSolanaウォレット | +| Access level | **Read** または **Read-write** | + +アクセスレベル： + +- **Read**：チケットとエスカレーション連絡先の閲覧、および読み取り専用APIキーの作成が可能。チケットの作成、更新、クローズはできません。 +- **Read-write**：チケットの作成、更新、クローズへのフルアクセス、および任意のレベルのAPIキーの作成が可能。 + +各チームメンバーは、Ops Managerキーを接続したのと同じ方法で、自分のウォレットでサインインします。 + +--- + +## 権限とエスカレーション + +### コントリビューターができること + +- 自分のデバイスとリンクに対してのみチケットを作成・管理できる。 +- 自分自身にチケットを割り当てるか、DZ/Malbeclabsにエスカレーションできる。 +- すべてのコントリビューターのすべてのチケットを閲覧できる。 +- チームメンバーを追加し、アクセスレベルを設定できる（ops managerのみ）。 +- 自分の組織のエスカレーション連絡先を管理できる（ops managerのみ）。 + +### DZ/Malbeclabs管理者ができること + +- 任意のコントリビューターのデバイスとリンクに対してチケットを作成できる。 +- コントリビューター間でチケットを割り当てまたは再割り当てできる。 +- エスカレーションとサポートリクエストを処理できる。 + +### DZXリンクの所有権 + +DZXリンクは、2つの異なるコントリビューターのデバイスを接続します。**A側**のコントリビューター（リンク名の最初のデバイス）がリンクを所有し、そのリンクに対してチケットを作成できる唯一のコントリビューターです。 + +**例：** リンク `deviceA:deviceB` の場合、`deviceA` を所有するコントリビューターがリンクを所有します。 + +**問題がZ側にある場合：** + +1. A側のコントリビューターがDZXリンクのチケットを作成します。 +2. チケットをDZ/Malbeclabsに割り当てます。 +3. DZ/Malbeclabsが調査し、必要に応じてZ側のコントリビューターに再割り当てします。 + +このワークフローには制限があることを認識しています。現在、Z側のコントリビューターは自分が所有していないDZXリンクのチケットを作成できないため、調整はDZ/Malbeclabsを経由する必要があります。DZXリンクの両側がインシデントとメンテナンスを独立して申告できるように、改善に取り組んでいます。 \ No newline at end of file diff --git a/docs/contribute-ops-management.ko.md b/docs/contribute-ops-management.ko.md new file mode 100644 index 0000000..3827bc0 --- /dev/null +++ b/docs/contribute-ops-management.ko.md @@ -0,0 +1,313 @@ +# OPS 관리 + +DoubleZero OPS 관리 포털은 기여자들이 네트워크 전반에 걸쳐 인시던트(계획되지 않은 장애)와 유지보수(계획된 작업)를 기록하고 추적하는 곳입니다. 모든 티켓은 모든 기여자에게 공개됩니다. + +**포털:** [https://doublezero.xyz/ops-management](https://doublezero.xyz/ops-management) + +## 포털 vs Slack + +OPS 관리 포털과 Slack은 함께 작동합니다. 모든 인시던트와 유지보수는 티켓으로 추적되며, 포털 또는 API를 통해 접근할 수 있습니다. 각 티켓은 적절한 Slack 채널에 자동으로 알림을 보내고, 모든 기여자에게 네트워크에서 일어나고 있는 일에 대한 공유 뷰를 제공합니다. Slack은 대화가 이루어지는 곳입니다: 로그 공유, 다른 기여자와의 조율, 활성 이슈에 대한 협업 등. + +티켓은 포털이든 API를 통해서든 생성된 정식 기록입니다. Slack 스레드는 그렇지 않습니다: 티켓 상태를 업데이트하지 않으며 영구적으로 저장되지 않습니다. 대화가 Slack에서 이루어지고 있더라도 항상 티켓 상태를 최신으로 유지하세요. + +포털과 Slack은 서로 다른 용도를 가집니다. 둘 다 사용하되, 올바른 용도에 맞게 사용하세요. + +| 포털(또는 API) 사용 용도... | Slack 사용 용도... | +|-------------------------------|-----------------| +| 티켓 열기, 업데이트, 닫기 | 활성 이슈에 대한 대화 및 협업 | +| 상태 전환 기록 | 로그, 스크린샷 공유 또는 통화 시작 | +| 티켓 할당 또는 에스컬레이션 | 문제에 대한 빠른 관심 확보 | +| 종료 시 근본 원인 설정 | 다른 기여자와의 조율 | + + + +--- + +## 온보딩 + +포털을 사용하기 전에 이 단계를 한 번 완료하세요. + +### 1. Ops Manager 키 설정 + +Solana 지갑 공개키를 Ops Manager 키로 등록합니다. 지원되는 지갑: Phantom, Solflare, Coinbase Wallet. + +```bash +doublezero contributor update \ + --ops-manager \ + --pubkey +``` + +### 2. 포털에서 지갑 연결 + +1. [https://doublezero.xyz/ops-management](https://doublezero.xyz/ops-management)로 이동합니다. +2. **Connect Your Wallet**을 클릭하고 지갑을 선택합니다. +3. Ops Manager 키의 소유권을 증명하기 위해 메시지에 서명합니다. + +인증이 완료되면 **Incident Tracking Table**이 표시됩니다. + +계정 설정은 **Settings** 메뉴(오른쪽 상단 톱니바퀴 아이콘) 뒤에 있습니다: API Key Management, User Management, Escalation Contacts. 표시되는 옵션은 역할에 따라 다릅니다. + +### 3. API 키 생성 (선택 사항) + +웹 양식 대신 프로그래밍 방식으로 접근하려면: + +1. **Settings** 메뉴(톱니바퀴 아이콘)를 열고 **API Key Management**를 선택합니다. +2. 하나 이상의 API 키를 생성합니다. +3. 이 페이지에서 API 문서를 다운로드합니다. + +--- + +## 인시던트 + +인시던트는 계획되지 않은 서비스 영향 이벤트입니다. + +### 심각도 수준 + +DoubleZero 네트워크에 대한 영향을 기반으로 심각도를 지정합니다. 상황이 변화함에 따라 심각도를 업데이트할 수 있습니다. + +| 심각도 | 영향 | 대응 | +|----------|--------|----------| +| `sev1` | 대체 수단이 없는 전면 장애 또는 주요 제어/데이터 플레인 고장 | 근무 시간 외라도 즉시 모든 것을 중단하고 대응합니다. DoubleZero Foundation에 즉시 에스컬레이션합니다. | +| `sev2` | 부분적이지만 상당한 영향; 대체 가능성이 있는 서비스 저하 | 긴급으로 처리합니다. 적극적으로 조율합니다. 지속적인 저하에 대해 야간 대응이 필요합니다. | +| `sev3` | 제한적이거나 사용자가 인지할 수 없는 영향; 해결되지 않으면 에스컬레이션될 가능성 | 근무 시간 내 최우선 순위입니다. 면밀히 모니터링합니다. 영향이 증가하지 않는 한 근무 시간 외 에스컬레이션은 불필요합니다. | + +??? note "심각도 예시" + + **Sev1 예시** + + - DoubleZero에서 사용자 트래픽의 10% 이상이 블랙홀링되고 공용 인터넷으로의 대체 불가 + - 사용자 온보딩, 연결 또는 연결 해제 시도의 80% 이상 실패 + - DZD의 20% 이상이 인터페이스 오류 보고 + - 컨트롤러가 DZD 에이전트에 유효하지만 잘못된 설정을 반환 + + **Sev2 예시** + + - 사용자의 20% 이상이 DoubleZero 터널을 통해 트래픽을 송수신할 수 없지만, 공용 인터넷으로 폴백 가능 + - 대체 없이 DoubleZero에서 사용자 트래픽의 0–10%가 블랙홀링 + - 신규 사용자 온보딩, 연결 또는 연결 해제 시도의 20–80% 실패 + - 설정 에이전트의 20% 이상이 DZD 설정 적용 실패 + - DZD의 0–20%가 인터페이스 오류 보고 + - 업스트림 문제로 인한 관찰성 손실 (모니터링/알림 다운) + - 온체인 데이터 파이프라인 다운 또는 잘못된 데이터 생성 + - 인터넷 지연 수집 또는 제출의 20% 이상 실패 + - DZD 에이전트가 컨트롤러에 접근 불가 + - 컨트롤러가 DZD에 적용되지 않을 잘못된 설정을 반환 + + **Sev3 예시** + + - 사용자의 0–20%가 DoubleZero 터널을 통해 트래픽을 송수신할 수 없지만, 공용 인터넷으로 폴백 가능 + - DZD의 0–20%가 인터페이스 오류 보고 + - DZD의 0–20%가 설정 에이전트 실패 경험 + - 사용자 온보딩, 연결 또는 연결 해제 시도의 0–20% 실패 + - 단일 데이터 제공업체의 인터넷 지연 수집 또는 제출의 20% 이상 실패 + - 모든 데이터 제공업체의 인터넷 지연 수집 또는 제출의 0–20% 실패 + - 음소거할 수 없는 알림 노이즈를 유발하는 버그 또는 기술 부채 + - 수 시간 동안 장치의 0–20%에 대해 DIA 다운 또는 레저 RPC 네트워킹 문제 + - 사소한 버그, 외관 오류 또는 고객 트래픽에 영향을 미치지 않는 격리된 인시던트와 같은 낮은 영향의 이슈 + - 서비스 중단 없이 간헐적으로 오류를 보고하는 소수의 장치 + +### 인시던트 열기 + +**Create New Record**를 클릭하고, 포털에서 Type = **Incident**를 선택하거나 API를 통해 제출합니다. + +**필수:** + +| 필드 | 설명 | +|-------|-------------| +| `title` | 짧은 요약 (최대 100자) | +| `description` | 상세한 설명 (최대 500자) | +| `severity` | `sev1`, `sev2`, 또는 `sev3` | +| `status` | 생성 시 종료 상태(`resolved`, `closed`)로 설정할 수 없음 | +| Device 및/또는 Link | 최소 하나 필수. 웹 양식에서는 드롭다운에서 장치 및 링크 코드를 선택합니다. API를 사용할 때는 해당하는 공개키를 `device_pubkey` 및/또는 `affected_link_pubkey`로 전달합니다. | + +**선택 사항:** + +| 필드 | 설명 | +|-------|-------------| +| `reporter_name` / `reporter_email` | 연락처 정보 | +| `assignee` | 해결 책임자 | +| `internal_reference` | 내부 티켓 ID (예: Jira, ServiceNow) | +| `start_at` | 기본값은 생성 시간; 편집 가능 | + +생성되면 티켓 ID, 심각도, 영향받는 장치/링크, 기여자 이름과 함께 기여자 인시던트 Slack 채널에 알림이 게시됩니다. + +### 인시던트 업데이트 + +인시던트가 진행됨에 따라 티켓 상태를 최신으로 유지하세요. 이것은 다른 기여자와 DZ가 무엇이 작업 중인지 이해하기 위해 사용하는 신호입니다. + +| 상태 | 설정 시점 | +|--------|----------------| +| `open` | 초기 상태: 이슈가 보고됨, 아직 작업 시작 전 | +| `acknowledged` | 확인했으며 소유권을 가짐 | +| `investigating` | 적극적으로 진단 중: 로그 수집, 메트릭 확인 | +| `mitigating` | 근본 원인이 파악되었거나 추정됨; 수정 또는 우회 방법 적용 중 | +| `monitoring` | 수정 적용됨; 유지되는지 확인하기 위해 관찰 중 | +| `resolved` | 이슈 수정 확인됨; **근본 원인 필수** | +| `closed` | 완전히 완료됨; 추가 조치 불필요; **근본 원인 필수** | + +``` +open → acknowledged → investigating → mitigating → monitoring → resolved → closed +``` + +적절한 경우 상태를 건너뛸 수 있습니다. 예를 들어, 즉시 작업을 시작하면 `open`에서 `investigating`으로 바로 이동할 수 있습니다. 항상 현재 상태에 가장 정확한 상태를 사용하세요. + +각 상태 업데이트는 원래 Slack 알림 스레드에 답변으로 게시됩니다. + +### 인시던트 종료 + +인시던트를 `resolved` 또는 `closed`로 이동하려면 **근본 원인**을 설정해야 합니다. 이미 알고 있다면 이전 단계에서 근본 원인을 설정할 수 있으며, 종료 시 필수가 됩니다. + +| 코드 | 설명 | +|------|-------------| +| `hardware` | 하드웨어 수리, 교체 또는 업그레이드 (SFP, NIC, 케이블, 장치) | +| `software` | 소프트웨어 또는 펌웨어 수정, 업데이트 또는 재시작 | +| `configuration` | 설정 변경, 수정 또는 롤백 | +| `capacity` | 혼잡, 용량 제한 또는 트래픽 관리 | +| `carrier` | 회선, 파장 또는 크로스 커넥트 제공업체 문제 | +| `network_external` | 기여자 통제 밖의 외부 네트워크 문제 | +| `facility` | 데이터센터 인프라 문제 (전원, 냉각) | +| `fiber_cut` | 물리적 광섬유 손상 복구 | +| `security` | 보안 인시던트 완화 | +| `human_error` | 운영 실수 수정 | +| `false_positive` | 조사 후 실제 문제가 발견되지 않음 | +| `duplicate` | 다른 티켓에서 이미 추적 중 | +| `self_resolved` | 개입 없이 이슈가 자체 해결됨 | +| `dz_managed` | DoubleZero 관리 소프트웨어 구성요소(activator, controller 등) 관련 문제 | + +--- + +## 유지보수 + +유지보수 기록은 가용성에 영향을 줄 수 있는 계획된 시간 제한 활동입니다. 다른 기여자들이 확인하고 충돌하는 시간대를 피할 수 있도록 사전에 생성하세요. + +### 유지보수 예약 + +포털에서 **Create New Record** > **Maintenance**를 클릭하거나 API를 통해 제출합니다. + +**필수:** + +| 필드 | 설명 | +|-------|-------------| +| `title` | 짧은 요약 (최대 100자) | +| `description` | 상세한 설명 (최대 500자) | +| `start_at` | 계획된 시작 시간 (UTC) | +| `end_at` | 계획된 종료 시간 (UTC); `start_at` 이후여야 함 | +| Device 및/또는 Link | 최소 하나 필수. 웹 양식에서는 드롭다운에서 장치 및 링크 코드를 선택합니다. API를 사용할 때는 해당하는 공개키를 `device_pubkey` 및/또는 `affected_link_pubkey`로 전달합니다. | + +생성되면 티켓 ID, 영향받는 장치/링크, 계획된 시간대, 기여자 이름과 함께 기여자 유지보수 Slack 채널에 알림이 게시됩니다. + +### 유지보수 상태 관리 + +시간대가 진행됨에 따라 상태를 최신으로 유지하세요. + +| 상태 | 설정 시점 | +|--------|----------------| +| `planned` | 예약됨, 아직 시작 전 | +| `in-progress` | 작업 시작됨 | +| `completed` | 작업이 성공적으로 완료됨 | +| `closed` | `end_at` 이후 24시간 뒤 자동 설정 | +| `cancelled` | 실행 전 또는 실행 중 취소됨 | + +``` +planned → in-progress → completed → closed (auto 24h after end_at) + ↓ ↓ + └──────────┴──→ cancelled +``` + +--- + +## 에스컬레이션 연락처 + +에스컬레이션 연락처는 네트워크의 해당 부분에 문제가 있을 때 DoubleZero와 다른 기여자들이 누구에게 연락해야 하는지 알려줍니다. 조직의 연락처를 직접 설정합니다. 연락처는 개인 또는 NOC와 같은 팀일 수 있습니다. 각 연락처에는 하나 이상의 연락 방법과 당직 일정이 있습니다. + +**Settings** 메뉴(톱니바퀴 아이콘)를 열고 **Escalation Contacts**를 선택합니다. ops manager만 연락처를 추가하거나 편집할 수 있습니다. + +### 연락처 추가 + +각 연락처에 대해 다음을 설정합니다: + +| 필드 | 설명 | +|-------|-------------| +| Name | 연락처 이름, 개인이든 NOC와 같은 팀이든 | +| Timezone | 일정을 읽는 데 사용되는 현지 시간대 | +| Availability | **24/7**, 또는 연락처가 당직인 하나 이상의 주간 시간대 | +| Contact methods | 연락처에 연락하는 하나 이상의 방법, 우선순위 순서 | + +지원되는 연락 방법은 이메일, 전화, Slack, Telegram, WhatsApp입니다. 순서가 중요합니다: 첫 번째 방법이 먼저 시도해야 할 방법입니다. + +### 가용성 및 커버리지 공백 + +연락처는 24시간(24/7) 가용하거나, 정의한 주간 시간대(예: 월요일~금요일, 09:00~17:00) 동안 가용합니다. 시간대는 연락처의 현지 시간대로 입력되고 UTC로 표시되므로, 일광 절약 시간이 자동으로 처리됩니다. + +**커버리지 공백** 뷰는 매주 조직에서 아무도 당직이 아닌 시간을 보여줍니다. 이를 사용하여 공백을 찾고 해소하세요. + +### 로테이션 윈도우 + +한 주는 30분 단위의 윈도우로 나뉩니다. 각 윈도우에 대해 연락처에 연락하는 순서를 설정할 수 있습니다. 이를 통해 각 연락처를 개별적으로 편집하지 않고도 당직 로테이션을 운영할 수 있습니다. + +### 가시성 + +연락처를 누가 볼 수 있는지 제어합니다. DoubleZero는 항상 볼 수 있습니다. 그 외에 누가 볼 수 있는지 선택합니다: + +| 설정 | 연락처를 볼 수 있는 대상 | +|---------|-------------------------------| +| DoubleZero only (기본값) | 다른 기여자 없음 | +| Everybody | 모든 기여자 | +| Some contributors | 선택한 기여자만 | + +소속 팀은 항상 연락처를 볼 수 있습니다. 가시성은 조직 전체에 한 번 설정되며 모든 연락처에 적용됩니다. + +--- + +## 사용자 관리 + +기본적으로 Ops Manager 키만 조직을 대신하여 활동할 수 있는 유일한 계정입니다. 여러 사람이 티켓을 관리할 수 있도록 팀원을 추가할 수 있습니다. + +**Settings** 메뉴(톱니바퀴 아이콘)를 열고 **User Management**를 선택합니다. ops manager만 팀원을 추가하거나 제거할 수 있습니다. + +각 팀원에 대해 다음을 설정합니다: + +| 필드 | 설명 | +|-------|-------------| +| Name | 해당 인물의 이름 | +| Wallet pubkey | 로그인 시 사용하는 Solana 지갑 | +| Access level | **Read** 또는 **Read-write** | + +접근 수준: + +- **Read**: 티켓과 에스컬레이션 연락처를 볼 수 있고, 읽기 전용 API 키를 생성할 수 있습니다. 티켓을 생성, 업데이트 또는 종료할 수 없습니다. +- **Read-write**: 티켓 생성, 업데이트, 종료에 대한 전체 접근 권한이 있으며, 모든 수준의 API 키를 생성할 수 있습니다. + +각 팀원은 Ops Manager 키를 연결했던 것과 같은 방식으로 자신의 지갑으로 로그인합니다. + +--- + +## 권한 및 에스컬레이션 + +### 기여자가 할 수 있는 것 + +- 자신의 장치와 링크에 대해서만 티켓을 생성하고 관리할 수 있습니다. +- 자신에게 티켓을 할당하거나 DZ/Malbeclabs에 에스컬레이션할 수 있습니다. +- 모든 기여자의 모든 티켓을 볼 수 있습니다. +- 팀원을 추가하고 접근 수준을 설정할 수 있습니다 (ops manager만 해당). +- 조직의 에스컬레이션 연락처를 관리할 수 있습니다 (ops manager만 해당). + +### DZ/Malbeclabs 관리자가 할 수 있는 것 + +- 모든 기여자의 장치와 링크에 대해 티켓을 생성할 수 있습니다. +- 기여자 간에 티켓을 할당하거나 재할당할 수 있습니다. +- 에스컬레이션과 지원 요청을 처리할 수 있습니다. + +### DZX 링크 소유권 + +DZX 링크는 서로 다른 두 기여자의 장치를 연결합니다. **A-side** 기여자(링크 이름의 첫 번째 장치)가 링크를 소유하며, 해당 링크에 대해 티켓을 생성할 수 있는 유일한 주체입니다. + +**예시:** `deviceA:deviceB` 링크의 경우, `deviceA`를 소유한 기여자가 링크를 소유합니다. + +**Z-side에 문제가 있는 경우:** + +1. A-side 기여자가 DZX 링크에 대한 티켓을 생성합니다. +2. 티켓을 DZ/Malbeclabs에 할당합니다. +3. DZ/Malbeclabs가 조사하고 필요 시 Z-side 기여자에게 재할당합니다. + +이 워크플로우가 제한적이라는 것을 인지하고 있습니다. 현재 Z-side 기여자는 소유하지 않은 DZX 링크에 대해 티켓을 생성할 수 없으므로, 조율이 DZ/Malbeclabs를 통해 이루어져야 합니다. DZX 링크의 양측이 독립적으로 인시던트와 유지보수를 선언할 수 있도록 개선 작업을 진행 중입니다. \ No newline at end of file diff --git a/docs/contribute-ops-management.pt.md b/docs/contribute-ops-management.pt.md new file mode 100644 index 0000000..89c266f --- /dev/null +++ b/docs/contribute-ops-management.pt.md @@ -0,0 +1,313 @@ +# Gestão OPS + +O portal de Gestão OPS do DoubleZero é onde os contribuidores registam e acompanham incidentes (interrupções não planeadas) e manutenções (trabalhos planeados) em toda a rede. Todos os tickets são visíveis para todos os contribuidores. + +**Portal:** [https://doublezero.xyz/ops-management](https://doublezero.xyz/ops-management) + +## Portal vs Slack + +O portal de Gestão OPS e o Slack funcionam em conjunto. Todos os incidentes e manutenções são rastreados como tickets, acessíveis através do portal ou da API. Cada ticket notifica automaticamente os canais Slack corretos e oferece a todos os contribuidores uma visão partilhada do que está a acontecer na rede. O Slack é onde a conversa acontece: partilhar logs, coordenar com outros contribuidores e colaborar em problemas ativos. + +Os tickets são o registo canónico, quer sejam criados pelo portal ou pela API. As threads do Slack não são: não atualizam o estado do ticket e não são armazenadas permanentemente. Mantenha sempre o estado do ticket atualizado, mesmo que a conversa esteja a decorrer no Slack. + +O portal e o Slack servem propósitos diferentes. Use ambos, mas para as finalidades certas. + +| Use o portal (ou API) para... | Use o Slack para... | +|-------------------------------|-----------------| +| Abrir, atualizar e fechar tickets | Conversa e colaboração sobre um problema ativo | +| Registar transições de estado | Partilhar logs, capturas de ecrã ou iniciar uma chamada | +| Atribuir ou escalar um ticket | Chamar rapidamente a atenção para um problema | +| Definir a causa raiz no encerramento | Coordenar com outros contribuidores | + + + +--- + +## Integração + +Complete estes passos uma vez antes de usar o portal. + +### 1. Defina a Sua Chave de Ops Manager + +Registe uma pubkey de carteira Solana como a sua chave de Ops Manager. Carteiras suportadas: Phantom, Solflare, Coinbase Wallet. + +```bash +doublezero contributor update \ + --ops-manager \ + --pubkey +``` + +### 2. Conecte a Sua Carteira no Portal + +1. Navegue até [https://doublezero.xyz/ops-management](https://doublezero.xyz/ops-management). +2. Clique em **Connect Your Wallet** e selecione a sua carteira. +3. Assine a mensagem para provar a propriedade da sua chave de Ops Manager. + +Uma vez autenticado, a **Tabela de Rastreamento de Incidentes** é apresentada. + +As definições da conta estão atrás do menu **Settings** (ícone de engrenagem, canto superior direito): API Key Management, User Management e Escalation Contacts. As opções que vê dependem do seu papel. + +### 3. Criar Chaves de API (Opcional) + +Para acesso programático em vez do formulário web: + +1. Abra o menu **Settings** (ícone de engrenagem) e escolha **API Key Management**. +2. Crie uma ou mais chaves de API. +3. Descarregue a documentação da API a partir desta página. + +--- + +## Incidentes + +Um incidente é um evento não planeado com impacto no serviço. + +### Níveis de Severidade + +Atribua a severidade com base no impacto na rede DoubleZero. Pode atualizar a severidade à medida que a situação evolui. + +| Severidade | Impacto | Resposta | +|----------|--------|----------| +| `sev1` | Interrupção total ou falha grave no plano de controlo/dados sem alternativa | Largue tudo imediatamente, mesmo fora do horário de trabalho. Escale para a DoubleZero Foundation imediatamente. | +| `sev2` | Impacto parcial mas substancial; serviço degradado com possível alternativa | Trate como urgente. Coordene ativamente. Resposta noturna necessária para degradação sustentada. | +| `sev3` | Impacto limitado ou sem impacto visível para o utilizador; potencial de escalar se não resolvido | Prioridade máxima durante o horário de trabalho. Monitorize de perto. Sem necessidade de escalação fora de horas, a menos que o impacto aumente. | + +??? note "Exemplos de severidade" + + **Exemplos Sev1** + + - Mais de 10% do tráfego de utilizadores perdido (blackholed) no DoubleZero, sem alternativa para internet pública + - Mais de 80% das tentativas de onboarding, conexão ou desconexão de utilizadores a falhar + - Mais de 20% dos DZDs a reportar erros de interface + - Controlador a devolver configurações válidas mas incorretas aos agentes DZD + + **Exemplos Sev2** + + - Mais de 20% dos utilizadores incapazes de enviar/receber tráfego através dos túneis DoubleZero, mas com fallback para internet pública + - 0–10% do tráfego de utilizadores perdido (blackholed) no DoubleZero sem alternativa + - 20–80% das novas tentativas de onboarding, conexão ou desconexão de utilizadores a falhar + - Mais de 20% dos agentes de configuração a falhar na aplicação da configuração DZD + - 0–20% dos DZDs a reportar erros de interface + - Problemas upstream a causar perda de observabilidade (monitorização/alertas em baixo) + - Pipeline de dados onchain em baixo ou a produzir dados incorretos + - Mais de 20% da recolha ou submissão de latência de internet a falhar + - Controlador inacessível pelos agentes DZD + - Controlador a devolver configurações inválidas aos DZDs que não serão aplicadas + + **Exemplos Sev3** + + - 0–20% dos utilizadores incapazes de enviar/receber tráfego através dos túneis DoubleZero, com fallback para internet pública + - 0–20% dos DZDs a reportar erros de interface + - 0–20% dos DZDs a experienciar falhas no agente de configuração + - 0–20% das tentativas de onboarding, conexão ou desconexão de utilizadores a falhar + - Mais de 20% da recolha ou submissão de latência de internet a falhar para um único fornecedor de dados + - 0–20% da recolha ou submissão de latência de internet a falhar para todos os fornecedores de dados + - Bugs ou dívida técnica a causar ruído de alertas que não pode ser silenciado + - DIA em baixo ou problemas de rede RPC do ledger para 0–20% dos dispositivos durante várias horas + - Problemas de baixo impacto como bugs menores, erros cosméticos ou incidentes isolados que não afetam o tráfego dos clientes + - Pequena fração de dispositivos a reportar erros intermitentes sem interrupção de serviço + +### Abrir um Incidente + +Clique em **Create New Record**, selecione Type = **Incident** no portal, ou submeta via API. + +**Obrigatório:** + +| Campo | Descrição | +|-------|-------------| +| `title` | Resumo curto (máximo 100 caracteres) | +| `description` | Explicação detalhada (máximo 500 caracteres) | +| `severity` | `sev1`, `sev2` ou `sev3` | +| `status` | Não pode ser definido para um estado terminal (`resolved`, `closed`) na criação | +| Dispositivo e/ou Link | Pelo menos um obrigatório. No formulário web, selecione a partir de um dropdown dos seus códigos de dispositivo e link. Ao usar a API, passe as pubkeys correspondentes como `device_pubkey` e/ou `affected_link_pubkey`. | + +**Opcional:** + +| Campo | Descrição | +|-------|-------------| +| `reporter_name` / `reporter_email` | Os seus dados de contacto | +| `assignee` | Quem é responsável pela resolução | +| `internal_reference` | O seu ID de ticket interno (ex.: Jira, ServiceNow) | +| `start_at` | Assume por defeito a hora de criação; editável | + +Uma vez criado, uma notificação é publicada no canal Slack de incidentes dos contribuidores com o ID do ticket, severidade, dispositivos/links afetados e nome do contribuidor. + +### Atualizar um Incidente + +À medida que o incidente progride, mantenha o estado do ticket atualizado. Este é o sinal que outros contribuidores e a DZ usam para compreender o que está a ser tratado. + +| Estado | Quando definir | +|--------|----------------| +| `open` | Estado inicial: problema reportado, ainda não está a ser tratado | +| `acknowledged` | Viu o problema e assumiu responsabilidade | +| `investigating` | A diagnosticar ativamente: a recolher logs, a verificar métricas | +| `mitigating` | Causa raiz conhecida ou suspeita; a aplicar correção ou solução temporária | +| `monitoring` | Correção aplicada; a monitorizar para confirmar que se mantém | +| `resolved` | Problema confirmado como resolvido; **causa raiz obrigatória** | +| `closed` | Totalmente concluído; sem mais ações; **causa raiz obrigatória** | + +``` +open → acknowledged → investigating → mitigating → monitoring → resolved → closed +``` + +Pode saltar estados se apropriado. Por exemplo, saltar diretamente de `open` para `investigating` se começar a trabalhar imediatamente. Use sempre o estado mais preciso para a situação atual. + +Cada atualização de estado publica uma resposta na thread da notificação Slack original. + +### Fechar um Incidente + +Para mover um incidente para `resolved` ou `closed`, uma **causa raiz** deve ser definida. Pode definir a causa raiz em qualquer fase anterior se já a conhecer; torna-se obrigatória no encerramento. + +| Código | Descrição | +|------|-------------| +| `hardware` | Reparação, substituição ou atualização de hardware (SFP, NIC, cabo, dispositivo) | +| `software` | Correção, atualização ou reinício de software ou firmware | +| `configuration` | Alteração, correção ou reversão de configuração | +| `capacity` | Congestionamento, limites de capacidade ou gestão de tráfego | +| `carrier` | Problema com circuito, comprimento de onda ou fornecedor de cross-connect | +| `network_external` | Problema de rede externo fora do controlo do contribuidor | +| `facility` | Problema de infraestrutura do datacenter (energia, refrigeração) | +| `fiber_cut` | Dano físico na fibra reparado | +| `security` | Incidente de segurança mitigado | +| `human_error` | Erro operacional corrigido | +| `false_positive` | Nenhum problema real encontrado após investigação | +| `duplicate` | Já rastreado noutro ticket | +| `self_resolved` | Problema resolvido sem intervenção | +| `dz_managed` | Problema com um componente de software gerido pelo DoubleZero (activator, controller, etc.) | + +--- + +## Manutenção + +Um registo de manutenção é uma atividade planeada, com limite temporal, que pode afetar a disponibilidade. Crie-o antecipadamente para que outros contribuidores possam ver e evitar janelas em conflito. + +### Agendar Manutenção + +Clique em **Create New Record** > **Maintenance** no portal, ou submeta via API. + +**Obrigatório:** + +| Campo | Descrição | +|-------|-------------| +| `title` | Resumo curto (máximo 100 caracteres) | +| `description` | Explicação detalhada (máximo 500 caracteres) | +| `start_at` | Hora de início planeada (UTC) | +| `end_at` | Hora de fim planeada (UTC); deve ser posterior a `start_at` | +| Dispositivo e/ou Link | Pelo menos um obrigatório. No formulário web, selecione a partir de um dropdown dos seus códigos de dispositivo e link. Ao usar a API, passe as pubkeys correspondentes como `device_pubkey` e/ou `affected_link_pubkey`. | + +Uma vez criado, uma notificação é publicada no canal Slack de manutenção dos contribuidores com o ID do ticket, dispositivos/links afetados, janela planeada e nome do contribuidor. + +### Gerir o Estado da Manutenção + +Mantenha o estado atualizado à medida que a janela progride. + +| Estado | Quando definir | +|--------|----------------| +| `planned` | Agendada, ainda não iniciada | +| `in-progress` | O trabalho começou | +| `completed` | Trabalho concluído com sucesso | +| `closed` | Definido automaticamente 24 horas após `end_at` | +| `cancelled` | Cancelada antes ou durante a execução | + +``` +planned → in-progress → completed → closed (auto 24h after end_at) + ↓ ↓ + └──────────┴──→ cancelled +``` + +--- + +## Contactos de Escalação + +Os contactos de escalação indicam ao DoubleZero e a outros contribuidores quem contactar quando a sua parte da rede tem um problema. Configura os seus próprios contactos para a sua organização. Um contacto pode ser uma pessoa ou uma equipa, como o seu NOC. Cada contacto tem uma ou mais formas de ser alcançado e um horário de quando está de serviço. + +Abra o menu **Settings** (ícone de engrenagem) e escolha **Escalation Contacts**. Apenas ops managers podem adicionar ou editar contactos. + +### Adicionar um Contacto + +Para cada contacto, defina: + +| Campo | Descrição | +|-------|-------------| +| Nome | Um nome para o contacto, seja uma pessoa ou uma equipa como o seu NOC | +| Fuso horário | O fuso horário local, usado para ler o horário | +| Disponibilidade | **24/7**, ou uma ou mais faixas horárias semanais em que o contacto está de serviço | +| Métodos de contacto | Uma ou mais formas de alcançar o contacto, por ordem de prioridade | + +Os métodos de contacto suportados são email, telefone, Slack, Telegram e WhatsApp. A ordem importa: o primeiro método é o que deve ser tentado primeiro. + +### Disponibilidade e Lacunas de Cobertura + +Um contacto está disponível permanentemente (24/7) ou disponível durante faixas horárias semanais que define, por exemplo de segunda a sexta, das 09:00 às 17:00. As faixas são introduzidas no fuso horário local do contacto e apresentadas em UTC, de modo que o horário de verão é tratado automaticamente. + +A vista de **lacunas de cobertura** mostra os horários de cada semana em que ninguém da sua organização está de serviço. Use-a para encontrar e colmatar lacunas. + +### Janelas de Rotação + +A semana é dividida em janelas de meia hora. Para cada janela pode definir a ordem em que os seus contactos são alcançados. Isto permite gerir uma rotação de serviço sem editar cada contacto individualmente. + +### Visibilidade + +Controla quem pode ver os seus contactos. O DoubleZero pode sempre vê-los. Escolhe quem mais pode: + +| Definição | Quem mais pode ver os seus contactos | +|---------|-------------------------------| +| Apenas DoubleZero (predefinição) | Nenhum outro contribuidor | +| Todos | Todos os contribuidores | +| Alguns contribuidores | Apenas os contribuidores que selecionar | + +A sua própria equipa pode sempre ver os seus contactos. A visibilidade é definida uma vez para toda a sua organização e aplica-se a todos os seus contactos. + +--- + +## Gestão de Utilizadores + +Por predefinição, a sua chave de Ops Manager é a única conta que pode agir em nome da sua organização. Pode adicionar membros da equipa para que mais do que uma pessoa possa gerir os seus tickets. + +Abra o menu **Settings** (ícone de engrenagem) e escolha **User Management**. Apenas ops managers podem adicionar ou remover membros da equipa. + +Para cada membro da equipa, defina: + +| Campo | Descrição | +|-------|-------------| +| Nome | O nome da pessoa | +| Pubkey da carteira | A carteira Solana com a qual iniciam sessão | +| Nível de acesso | **Read** ou **Read-write** | + +Níveis de acesso: + +- **Read**: pode ver tickets e contactos de escalação, e criar chaves de API apenas de leitura. Não pode criar, atualizar ou fechar tickets. +- **Read-write**: acesso total para criar, atualizar e fechar tickets, e pode criar chaves de API de qualquer nível. + +Cada membro da equipa inicia sessão com a sua própria carteira, da mesma forma que conectou a sua chave de Ops Manager. + +--- + +## Permissões e Escalação + +### O Que os Contribuidores Podem Fazer + +- Criar e gerir tickets apenas para os seus próprios dispositivos e links. +- Atribuir tickets a si próprios ou escalar para DZ/Malbeclabs. +- Ver todos os tickets de todos os contribuidores. +- Adicionar membros da equipa e definir o seu nível de acesso (apenas ops managers). +- Gerir contactos de escalação da sua organização (apenas ops managers). + +### O Que os Admins DZ/Malbeclabs Podem Fazer + +- Criar tickets para dispositivos e links de qualquer contribuidor. +- Atribuir ou reatribuir tickets entre contribuidores. +- Tratar escalações e pedidos de suporte. + +### Propriedade de Links DZX + +Os links DZX conectam dispositivos de dois contribuidores diferentes. O contribuidor do **lado A** (primeiro dispositivo no nome do link) é o proprietário do link e é o único que pode criar tickets para ele. + +**Exemplo:** Para o link `deviceA:deviceB`, o contribuidor que detém `deviceA` é o proprietário do link. + +**Se o problema está no lado Z:** + +1. O contribuidor do lado A cria um ticket para o link DZX. +2. Atribui o ticket a DZ/Malbeclabs. +3. DZ/Malbeclabs investiga e reatribui ao contribuidor do lado Z se necessário. + +Reconhecemos que este fluxo de trabalho é limitado. Atualmente, os contribuidores do lado Z não podem criar tickets para links DZX que não possuem, o que significa que a coordenação tem de passar por DZ/Malbeclabs. Estamos a trabalhar para melhorar isto de modo que ambos os lados de um link DZX possam declarar incidentes e manutenções de forma independente. \ No newline at end of file diff --git a/docs/contribute-ops-management.zh.md b/docs/contribute-ops-management.zh.md new file mode 100644 index 0000000..ac65dd2 --- /dev/null +++ b/docs/contribute-ops-management.zh.md @@ -0,0 +1,313 @@ +# OPS 管理 + +DoubleZero OPS 管理门户是贡献者记录和跟踪事件（计划外中断）和维护（计划性工作）的地方。所有工单对所有贡献者可见。 + +**门户：** [https://doublezero.xyz/ops-management](https://doublezero.xyz/ops-management) + +## 门户与 Slack + +OPS 管理门户和 Slack 协同工作。所有事件和维护都以工单形式跟踪，可通过门户或 API 访问。每个工单会自动通知对应的 Slack 频道，并为每个贡献者提供网络当前状况的共享视图。Slack 是进行对话的地方：共享日志、与其他贡献者协调以及协作处理活跃问题。 + +工单是权威记录，无论是通过门户还是 API 创建。Slack 对话则不是：它们不会更新工单状态，也不会永久存储。即使对话发生在 Slack 中，也请始终保持工单状态为最新。 + +门户和 Slack 服务于不同目的。两者都要使用，但要用在正确的场景。 + +| 使用门户（或 API）进行... | 使用 Slack 进行... | +|-------------------------------|-----------------| +| 创建、更新和关闭工单 | 就活跃问题进行对话和协作 | +| 记录状态变更 | 共享日志、截图或发起通话 | +| 分配或升级工单 | 快速引起他人关注某个问题 | +| 关闭时设置根本原因 | 与其他贡献者协调 | + + + +--- + +## 入门准备 + +在使用门户之前，请完成以下一次性步骤。 + +### 1. 设置您的 Ops Manager 密钥 + +注册一个 Solana 钱包公钥作为您的 Ops Manager 密钥。支持的钱包：Phantom、Solflare、Coinbase Wallet。 + +```bash +doublezero contributor update \ + --ops-manager \ + --pubkey +``` + +### 2. 在门户上连接您的钱包 + +1. 导航至 [https://doublezero.xyz/ops-management](https://doublezero.xyz/ops-management)。 +2. 点击 **Connect Your Wallet** 并选择您的钱包。 +3. 签署消息以证明您对 Ops Manager 密钥的所有权。 + +认证完成后，**Incident Tracking Table** 将显示。 + +账户设置位于 **Settings** 菜单（右上角齿轮图标）下方：API Key Management、User Management 和 Escalation Contacts。您看到的选项取决于您的角色。 + +### 3. 创建 API 密钥（可选） + +如需通过编程方式访问而非使用 Web 表单： + +1. 打开 **Settings** 菜单（齿轮图标）并选择 **API Key Management**。 +2. 创建一个或多个 API 密钥。 +3. 从此页面下载 API 文档。 + +--- + +## 事件 + +事件是计划外的影响服务的事件。 + +### 严重级别 + +根据对 DoubleZero 网络的影响分配严重级别。您可以随着情况变化更新严重级别。 + +| 严重级别 | 影响 | 响应 | +|----------|--------|----------| +| `sev1` | 完全中断或重大控制/数据平面故障，无备用方案 | 立即放下一切工作，即使在非工作时间。立即升级至 DoubleZero Foundation。 | +| `sev2` | 部分但重大影响；服务降级，可能有备用方案 | 视为紧急事项。积极协调。持续降级需要夜间响应。 | +| `sev3` | 有限或无用户可感知的影响；如未解决可能升级 | 工作时间内的最高优先级。密切监控。除非影响加大，否则无需非工作时间升级。 | + +??? note "严重级别示例" + + **Sev1 示例** + + - 超过 10% 的用户流量在 DoubleZero 上被丢弃，无法回退到公共互联网 + - 超过 80% 的用户上线、连接或断开尝试失败 + - 超过 20% 的 DZD 报告接口错误 + - Controller 向 DZD 代理返回有效但不正确的配置 + + **Sev2 示例** + + - 超过 20% 的用户无法通过 DoubleZero 隧道发送/接收流量，但可回退到公共互联网 + - 0–10% 的用户流量在 DoubleZero 上被丢弃且无备用方案 + - 20–80% 的新用户上线、连接或断开尝试失败 + - 超过 20% 的配置代理无法应用 DZD 配置 + - 0–20% 的 DZD 报告接口错误 + - 上游问题导致可观测性丧失（监控/告警中断） + - 链上数据管道中断或产生不正确的数据 + - 超过 20% 的互联网延迟采集或提交失败 + - DZD 代理无法访问 Controller + - Controller 向 DZD 返回无效配置且不会被应用 + + **Sev3 示例** + + - 0–20% 的用户无法通过 DoubleZero 隧道发送/接收流量，可回退到公共互联网 + - 0–20% 的 DZD 报告接口错误 + - 0–20% 的 DZD 遇到配置代理故障 + - 0–20% 的用户上线、连接或断开尝试失败 + - 单个数据提供商超过 20% 的互联网延迟采集或提交失败 + - 所有数据提供商 0–20% 的互联网延迟采集或提交失败 + - Bug 或技术债务导致无法静默的告警噪音 + - DIA 中断或账本 RPC 网络问题影响 0–20% 的设备持续数小时 + - 低影响问题，如小 Bug、外观错误或不影响客户流量的孤立事件 + - 少量设备间歇性报告错误但未造成服务中断 + +### 创建事件 + +点击 **Create New Record**，在门户上选择 Type = **Incident**，或通过 API 提交。 + +**必填：** + +| 字段 | 描述 | +|-------|-------------| +| `title` | 简短摘要（最多 100 个字符） | +| `description` | 详细说明（最多 500 个字符） | +| `severity` | `sev1`、`sev2` 或 `sev3` | +| `status` | 创建时不能设置为终态（`resolved`、`closed`） | +| 设备和/或链路 | 至少需要一个。在 Web 表单上，从下拉列表中选择您的设备和链路代码。使用 API 时，将对应的公钥作为 `device_pubkey` 和/或 `affected_link_pubkey` 传递。 | + +**可选：** + +| 字段 | 描述 | +|-------|-------------| +| `reporter_name` / `reporter_email` | 您的联系方式 | +| `assignee` | 负责解决问题的人 | +| `internal_reference` | 您的内部工单 ID（例如 Jira、ServiceNow） | +| `start_at` | 默认为创建时间；可编辑 | + +创建后，将在贡献者事件 Slack 频道中发布通知，包含工单 ID、严重级别、受影响的设备/链路和贡献者名称。 + +### 更新事件 + +随着事件进展，请保持工单状态为最新。这是其他贡献者和 DZ 了解正在处理什么问题的信号。 + +| 状态 | 何时设置 | +|--------|----------------| +| `open` | 初始状态：问题已报告，尚未开始处理 | +| `acknowledged` | 您已看到并承担责任 | +| `investigating` | 正在积极诊断：收集日志、检查指标 | +| `mitigating` | 根本原因已知或疑似；正在应用修复或变通方案 | +| `monitoring` | 修复已应用；正在观察以确认是否有效 | +| `resolved` | 问题已确认修复；**需要填写根本原因** | +| `closed` | 完全结束；无需进一步操作；**需要填写根本原因** | + +``` +open → acknowledged → investigating → mitigating → monitoring → resolved → closed +``` + +如果合适，可以跳过某些状态。例如，如果您立即开始处理，可以直接从 `open` 跳转到 `investigating`。始终使用最准确反映当前状态的状态。 + +每次状态更新都会在原始 Slack 通知线程中发布一条回复。 + +### 关闭事件 + +要将事件移至 `resolved` 或 `closed` 状态，必须设置**根本原因**。如果您已经知道根本原因，可以在更早的阶段设置；在关闭时它是强制性的。 + +| 代码 | 描述 | +|------|-------------| +| `hardware` | 硬件维修、更换或升级（SFP、NIC、线缆、设备） | +| `software` | 软件或固件修复、更新或重启 | +| `configuration` | 配置变更、修复或回滚 | +| `capacity` | 拥塞、容量限制或流量管理 | +| `carrier` | 电路、波长或交叉连接提供商问题 | +| `network_external` | 贡献者控制范围外的外部网络问题 | +| `facility` | 数据中心基础设施问题（电力、冷却） | +| `fiber_cut` | 物理光纤损坏已修复 | +| `security` | 安全事件已缓解 | +| `human_error` | 操作失误已纠正 | +| `false_positive` | 调查后未发现实际问题 | +| `duplicate` | 已在另一个工单中跟踪 | +| `self_resolved` | 问题在无人干预的情况下自行解决 | +| `dz_managed` | DoubleZero 管理的软件组件问题（activator、controller 等） | + +--- + +## 维护 + +维护记录是可能影响可用性的计划性、有时间限制的活动。请提前创建，以便其他贡献者可以查看并避免窗口冲突。 + +### 计划维护 + +在门户上点击 **Create New Record** > **Maintenance**，或通过 API 提交。 + +**必填：** + +| 字段 | 描述 | +|-------|-------------| +| `title` | 简短摘要（最多 100 个字符） | +| `description` | 详细说明（最多 500 个字符） | +| `start_at` | 计划开始时间（UTC） | +| `end_at` | 计划结束时间（UTC）；必须晚于 `start_at` | +| 设备和/或链路 | 至少需要一个。在 Web 表单上，从下拉列表中选择您的设备和链路代码。使用 API 时，将对应的公钥作为 `device_pubkey` 和/或 `affected_link_pubkey` 传递。 | + +创建后，将在贡献者维护 Slack 频道中发布通知，包含工单 ID、受影响的设备/链路、计划窗口和贡献者名称。 + +### 管理维护状态 + +随着维护窗口的推进，请保持状态为最新。 + +| 状态 | 何时设置 | +|--------|----------------| +| `planned` | 已计划，尚未开始 | +| `in-progress` | 工作已开始 | +| `completed` | 工作已成功完成 | +| `closed` | 在 `end_at` 后 24 小时自动设置 | +| `cancelled` | 在执行之前或期间取消 | + +``` +planned → in-progress → completed → closed (auto 24h after end_at) + ↓ ↓ + └──────────┴──→ cancelled +``` + +--- + +## 升级联系人 + +升级联系人告诉 DoubleZero 和其他贡献者，当您负责的网络部分出现问题时应联系谁。您为自己的组织设置联系人。联系人可以是个人或团队，例如您的 NOC。每个联系人有一种或多种联系方式以及值班时间表。 + +打开 **Settings** 菜单（齿轮图标）并选择 **Escalation Contacts**。只有 ops manager 可以添加或编辑联系人。 + +### 添加联系人 + +为每个联系人设置： + +| 字段 | 描述 | +|-------|-------------| +| Name | 联系人名称，可以是个人或团队（如您的 NOC） | +| Timezone | 当地时区，用于解读时间表 | +| Availability | **24/7**，或一个或多个每周值班时间段 | +| Contact methods | 一种或多种联系方式，按优先级排序 | + +支持的联系方式包括电子邮件、电话、Slack、Telegram 和 WhatsApp。顺序很重要：第一种方式是首先尝试的方式。 + +### 可用性和覆盖空白 + +联系人要么全天候（24/7）可用，要么在您定义的每周时间段内可用，例如周一至周五，09:00 至 17:00。时间段以联系人的当地时区输入，并以 UTC 显示，因此夏令时会自动处理。 + +**coverage gaps**（覆盖空白）视图显示每周您的组织中无人值班的时间段。使用它来发现并填补空白。 + +### 轮换窗口 + +一周被分为半小时的窗口。对于每个窗口，您可以设置联系人的联系顺序。这使您可以运行值班轮换而无需编辑每个联系人。 + +### 可见性 + +您可以控制谁能看到您的联系人。DoubleZero 始终可以看到。您可以选择其他人是否可以看到： + +| 设置 | 还有谁可以看到您的联系人 | +|---------|-------------------------------| +| 仅 DoubleZero（默认） | 没有其他贡献者 | +| 所有人 | 所有贡献者 | +| 部分贡献者 | 仅您选择的贡献者 | + +您自己的团队始终可以看到您的联系人。可见性为整个组织统一设置，适用于您的所有联系人。 + +--- + +## 用户管理 + +默认情况下，您的 Ops Manager 密钥是唯一能代表您的组织操作的账户。您可以添加团队成员，使多人能够管理您的工单。 + +打开 **Settings** 菜单（齿轮图标）并选择 **User Management**。只有 ops manager 可以添加或移除团队成员。 + +为每个团队成员设置： + +| 字段 | 描述 | +|-------|-------------| +| Name | 该人员的姓名 | +| Wallet pubkey | 用于登录的 Solana 钱包 | +| Access level | **Read** 或 **Read-write** | + +访问级别： + +- **Read**：可以查看工单和升级联系人，并创建只读 API 密钥。不能创建、更新或关闭工单。 +- **Read-write**：拥有创建、更新和关闭工单的完整权限，可以创建任何级别的 API 密钥。 + +每个团队成员使用自己的钱包登录，方式与您连接 Ops Manager 密钥时相同。 + +--- + +## 权限和升级 + +### 贡献者可以做什么 + +- 仅为自己的设备和链路创建和管理工单。 +- 将工单分配给自己或升级至 DZ/Malbeclabs。 +- 查看所有贡献者的所有工单。 +- 添加团队成员并设置其访问级别（仅限 ops manager）。 +- 管理其组织的升级联系人（仅限 ops manager）。 + +### DZ/Malbeclabs 管理员可以做什么 + +- 为任何贡献者的设备和链路创建工单。 +- 在贡献者之间分配或重新分配工单。 +- 处理升级和支持请求。 + +### DZX 链路所有权 + +DZX 链路连接来自两个不同贡献者的设备。**A 侧**贡献者（链路名称中的第一个设备）拥有该链路，是唯一可以为其创建工单的贡献者。 + +**示例：** 对于链路 `deviceA:deviceB`，拥有 `deviceA` 的贡献者拥有该链路。 + +**如果问题在 Z 侧：** + +1. A 侧贡献者为 DZX 链路创建工单。 +2. 将工单分配给 DZ/Malbeclabs。 +3. DZ/Malbeclabs 进行调查，如有需要则重新分配给 Z 侧贡献者。 + +我们认识到此工作流程存在局限性。Z 侧贡献者目前无法为其不拥有的 DZX 链路创建工单，这意味着协调必须通过 DZ/Malbeclabs 进行。我们正在努力改进，使 DZX 链路的双方都能独立声明事件和维护。 \ No newline at end of file From e202f43f954ed17f7b0750804b9b64ace8de8926 Mon Sep 17 00:00:00 2001 From: Thijs van Emmerik Date: Thu, 4 Jun 2026 07:56:53 +0000 Subject: [PATCH 3/4] docs: note severity is required for maintenance tickets --- docs/contribute-ops-management.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/contribute-ops-management.md b/docs/contribute-ops-management.md index e902945..e864c08 100644 --- a/docs/contribute-ops-management.md +++ b/docs/contribute-ops-management.md @@ -190,10 +190,13 @@ Click **Create New Record** > **Maintenance** on the portal, or submit via the A |-------|-------------| | `title` | Short summary (max 100 characters) | | `description` | Detailed explanation (max 500 characters) | +| `severity` | `sev1`, `sev2`, or `sev3`. Set it to the expected user impact (see note below). | | `start_at` | Planned start time (UTC) | | `end_at` | Planned end time (UTC); must be after `start_at` | | Device and/or Link | At least one required. On the web form, select from a dropdown of your device and link codes. When using the API, pass the corresponding pubkeys as `device_pubkey` and/or `affected_link_pubkey`. | +Severity applies to maintenance the same way it does to incidents. Set it to the user impact you expect during the window, using the [severity levels above](#severity-levels). + Once created, a notification is posted to the contributor maintenance Slack channel with the ticket ID, affected devices/links, planned window, and contributor name. ### Managing Maintenance Status From fe09380dbded3c48537ef651c475b3132e847ef1 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 4 Jun 2026 08:11:18 +0000 Subject: [PATCH 4/4] chore: auto-translate docs --- docs/contribute-ops-management.es.md | 137 +++++++++---------- docs/contribute-ops-management.fr.md | 125 +++++++++--------- docs/contribute-ops-management.it.md | 137 +++++++++---------- docs/contribute-ops-management.ja.md | 189 +++++++++++++------------- docs/contribute-ops-management.ko.md | 191 ++++++++++++++------------- docs/contribute-ops-management.pt.md | 89 +++++++------ docs/contribute-ops-management.zh.md | 159 +++++++++++----------- 7 files changed, 524 insertions(+), 503 deletions(-) diff --git a/docs/contribute-ops-management.es.md b/docs/contribute-ops-management.es.md index df311dc..9b84476 100644 --- a/docs/contribute-ops-management.es.md +++ b/docs/contribute-ops-management.es.md @@ -1,21 +1,21 @@ -# Gestión OPS +# Gestión de OPS -El portal de Gestión OPS de DoubleZero es donde los contribuidores registran y hacen seguimiento de incidentes (interrupciones no planificadas) y mantenimientos (trabajos planificados) en toda la red. Todos los tickets son visibles para todos los contribuidores. +El portal de Gestión de OPS de DoubleZero es donde los contribuidores registran y hacen seguimiento de incidentes (interrupciones no planificadas) y mantenimientos (trabajos planificados) en toda la red. Todos los tickets son visibles para todos los contribuidores. **Portal:** [https://doublezero.xyz/ops-management](https://doublezero.xyz/ops-management) ## Portal vs Slack -El portal de Gestión OPS y Slack trabajan juntos. Todos los incidentes y mantenimientos se registran como tickets, accesibles a través del portal o la API. Cada ticket notifica automáticamente a los canales de Slack correspondientes y proporciona a cada contribuidor una vista compartida de lo que está ocurriendo en la red. Slack es donde sucede la conversación: compartir registros, coordinarse con otros contribuidores y colaborar en problemas activos. +El portal de Gestión de OPS y Slack trabajan juntos. Todos los incidentes y mantenimientos se rastrean como tickets, accesibles a través del portal o la API. Cada ticket notifica automáticamente a los canales de Slack correspondientes y ofrece a cada contribuidor una vista compartida de lo que está ocurriendo en la red. Slack es donde ocurre la conversación: compartir logs, coordinarse con otros contribuidores y colaborar en problemas activos. -Los tickets son el registro canónico, ya sean creados a través del portal o la API. Los hilos de Slack no lo son: no actualizan el estado del ticket y no se almacenan de forma permanente. Mantén siempre el estado del ticket actualizado, incluso si la conversación está ocurriendo en Slack. +Los tickets son el registro canónico, ya sea que se creen a través del portal o la API. Los hilos de Slack no lo son: no actualizan el estado del ticket y no se almacenan de forma permanente. Mantén siempre el estado del ticket actualizado, incluso si la conversación está ocurriendo en Slack. El portal y Slack sirven para propósitos diferentes. Usa ambos, pero para las cosas adecuadas. | Usa el portal (o la API) para... | Usa Slack para... | |-------------------------------|-----------------| | Abrir, actualizar y cerrar tickets | Conversación y colaboración sobre un problema activo | -| Registrar transiciones de estado | Compartir registros, capturas de pantalla o iniciar una llamada | +| Registrar transiciones de estado | Compartir logs, capturas de pantalla o iniciar una llamada | | Asignar o escalar un ticket | Conseguir atención rápida sobre un problema | | Establecer la causa raíz al cerrar | Coordinarse con otros contribuidores | @@ -27,9 +27,9 @@ El portal y Slack sirven para propósitos diferentes. Usa ambos, pero para las c Completa estos pasos una vez antes de usar el portal. -### 1. Configura tu clave de Ops Manager +### 1. Configura Tu Clave de Ops Manager -Registra una pubkey de wallet de Solana como tu clave de Ops Manager. Wallets compatibles: Phantom, Solflare, Coinbase Wallet. +Registra una clave pública de billetera Solana como tu clave de Ops Manager. Billeteras compatibles: Phantom, Solflare, Coinbase Wallet. ```bash doublezero contributor update \ @@ -37,21 +37,21 @@ doublezero contributor update \ --pubkey ``` -### 2. Conecta tu wallet en el portal +### 2. Conecta Tu Billetera en el Portal 1. Navega a [https://doublezero.xyz/ops-management](https://doublezero.xyz/ops-management). -2. Haz clic en **Connect Your Wallet** y selecciona tu wallet. +2. Haz clic en **Connect Your Wallet** y selecciona tu billetera. 3. Firma el mensaje para demostrar la propiedad de tu clave de Ops Manager. -Una vez autenticado, se muestra la **Tabla de seguimiento de incidentes**. +Una vez autenticado, se muestra la **Tabla de Seguimiento de Incidentes**. -La configuración de la cuenta se encuentra detrás del menú **Settings** (el icono de engranaje, arriba a la derecha): Gestión de claves API, Gestión de usuarios y Contactos de escalación. Las opciones que ves dependen de tu rol. +La configuración de la cuenta se encuentra detrás del menú **Settings** (el ícono de engranaje, arriba a la derecha): API Key Management, User Management y Escalation Contacts. Las opciones que ves dependen de tu rol. -### 3. Crear claves API (opcional) +### 3. Crear Claves API (Opcional) Para acceso programático en lugar del formulario web: -1. Abre el menú **Settings** (icono de engranaje) y elige **API Key Management**. +1. Abre el menú **Settings** (ícono de engranaje) y elige **API Key Management**. 2. Crea una o más claves API. 3. Descarga la documentación de la API desde esta página. @@ -61,15 +61,15 @@ Para acceso programático en lugar del formulario web: Un incidente es un evento no planificado que impacta el servicio. -### Niveles de severidad +### Niveles de Severidad -Asigna la severidad según el impacto en la red de DoubleZero. Puedes actualizar la severidad a medida que la situación evoluciona. +Asigna la severidad según el impacto en la red DoubleZero. Puedes actualizar la severidad a medida que la situación evoluciona. | Severidad | Impacto | Respuesta | |----------|--------|----------| -| `sev1` | Interrupción total o rotura importante del plano de control/datos sin alternativa | Deja todo inmediatamente, incluso fuera del horario laboral. Escala a la Fundación DoubleZero de inmediato. | -| `sev2` | Impacto parcial pero sustancial; servicio degradado con posible alternativa | Tratar como urgente. Coordinar activamente. Se requiere respuesta nocturna para degradación sostenida. | -| `sev3` | Impacto limitado o no visible para el usuario; potencial de escalar si no se resuelve | Máxima prioridad durante el horario laboral. Monitorear de cerca. No se requiere escalación fuera de horario a menos que el impacto aumente. | +| `sev1` | Interrupción total o fallo mayor del plano de control/datos sin alternativa | Deja todo inmediatamente, incluso fuera del horario laboral. Escala a DoubleZero Foundation de inmediato. | +| `sev2` | Impacto parcial pero sustancial; servicio degradado con posible alternativa | Tratar como urgente. Coordinar activamente. Se requiere respuesta nocturna ante degradación sostenida. | +| `sev3` | Impacto limitado o no visible para el usuario; potencial de escalar si no se resuelve | Máxima prioridad durante horario laboral. Monitorear de cerca. No se requiere escalación fuera de horario a menos que el impacto aumente. | ??? note "Ejemplos de severidad" @@ -82,10 +82,10 @@ Asigna la severidad según el impacto en la red de DoubleZero. Puedes actualizar **Ejemplos de Sev2** - - Más del 20% de los usuarios sin poder enviar/recibir tráfico por túneles de DoubleZero, pero con alternativa a internet público + - Más del 20% de los usuarios sin poder enviar/recibir tráfico a través de túneles DoubleZero, pero con alternativa a internet público - 0–10% del tráfico de usuarios descartado en DoubleZero sin alternativa - 20–80% de los nuevos intentos de incorporación, conexión o desconexión de usuarios fallando - - Más del 20% de los agentes de configuración sin poder aplicar la configuración de DZD + - Más del 20% de los agentes de configuración sin poder aplicar la configuración DZD - 0–20% de los DZDs reportando errores de interfaz - Problemas upstream causando pérdida de observabilidad (monitoreo/alertas caídos) - Pipeline de datos onchain caído o produciendo datos incorrectos @@ -95,20 +95,20 @@ Asigna la severidad según el impacto en la red de DoubleZero. Puedes actualizar **Ejemplos de Sev3** - - 0–20% de los usuarios sin poder enviar/recibir tráfico por túneles de DoubleZero, con alternativa a internet público + - 0–20% de los usuarios sin poder enviar/recibir tráfico a través de túneles DoubleZero, con alternativa a internet público - 0–20% de los DZDs reportando errores de interfaz - 0–20% de los DZDs experimentando fallos del agente de configuración - 0–20% de los intentos de incorporación, conexión o desconexión de usuarios fallando - Más del 20% de la recolección o envío de latencia de internet fallando para un solo proveedor de datos - 0–20% de la recolección o envío de latencia de internet fallando para todos los proveedores de datos - - Bugs o deuda técnica causando ruido en las alertas que no puede ser silenciado + - Bugs o deuda técnica causando ruido en alertas que no se puede silenciar - DIA caído o problemas de red del ledger RPC para 0–20% de los dispositivos durante varias horas - Problemas de bajo impacto como bugs menores, errores cosméticos o incidentes aislados que no afectan el tráfico de clientes - - Una pequeña fracción de dispositivos reportando errores intermitentes sin interrupción del servicio + - Pequeña fracción de dispositivos reportando errores intermitentemente sin interrupción del servicio -### Abrir un incidente +### Abrir un Incidente -Haz clic en **Create New Record**, selecciona Type = **Incident** en el portal, o envía a través de la API. +Haz clic en **Create New Record**, selecciona Type = **Incident** en el portal, o envíalo a través de la API. **Obligatorio:** @@ -116,9 +116,9 @@ Haz clic en **Create New Record**, selecciona Type = **Incident** en el portal, |-------|-------------| | `title` | Resumen breve (máximo 100 caracteres) | | `description` | Explicación detallada (máximo 500 caracteres) | -| `severity` | `sev1`, `sev2` o `sev3` | +| `severity` | `sev1`, `sev2`, o `sev3` | | `status` | No se puede establecer en un estado terminal (`resolved`, `closed`) al crear | -| Dispositivo y/o Enlace | Al menos uno obligatorio. En el formulario web, selecciona de un desplegable con los códigos de tus dispositivos y enlaces. Al usar la API, pasa las pubkeys correspondientes como `device_pubkey` y/o `affected_link_pubkey`. | +| Dispositivo y/o Enlace | Se requiere al menos uno. En el formulario web, selecciona desde un menú desplegable de tus códigos de dispositivo y enlace. Al usar la API, pasa las claves públicas correspondientes como `device_pubkey` y/o `affected_link_pubkey`. | **Opcional:** @@ -129,9 +129,9 @@ Haz clic en **Create New Record**, selecciona Type = **Incident** en el portal, | `internal_reference` | Tu ID de ticket interno (ej. Jira, ServiceNow) | | `start_at` | Por defecto es la hora de creación; editable | -Una vez creado, se publica una notificación en el canal de Slack de incidentes de contribuidores con el ID del ticket, la severidad, los dispositivos/enlaces afectados y el nombre del contribuidor. +Una vez creado, se publica una notificación en el canal de Slack de incidentes de contribuidores con el ID del ticket, severidad, dispositivos/enlaces afectados y nombre del contribuidor. -### Actualizar un incidente +### Actualizar un Incidente A medida que el incidente progresa, mantén el estado del ticket actualizado. Esta es la señal que otros contribuidores y DZ usan para entender en qué se está trabajando. @@ -139,8 +139,8 @@ A medida que el incidente progresa, mantén el estado del ticket actualizado. Es |--------|----------------| | `open` | Estado inicial: problema reportado, aún no se está trabajando en él | | `acknowledged` | Lo has visto y has tomado responsabilidad | -| `investigating` | Diagnosticando activamente: recopilando registros, verificando métricas | -| `mitigating` | Causa raíz conocida o sospechada; aplicando una solución o alternativa | +| `investigating` | Diagnosticando activamente: recopilando logs, revisando métricas | +| `mitigating` | Causa raíz conocida o sospechada; aplicando una solución o solución alternativa | | `monitoring` | Solución aplicada; observando para confirmar que se mantiene | | `resolved` | Problema confirmado como resuelto; **causa raíz obligatoria** | | `closed` | Completamente finalizado; sin más acciones; **causa raíz obligatoria** | @@ -149,11 +149,11 @@ A medida que el incidente progresa, mantén el estado del ticket actualizado. Es open → acknowledged → investigating → mitigating → monitoring → resolved → closed ``` -Puedes omitir estados si es apropiado. Por ejemplo, saltar directamente de `open` a `investigating` si comienzas a trabajar en ello inmediatamente. Usa siempre el estado más preciso para la situación actual. +Puedes omitir estados si es apropiado. Por ejemplo, saltar directamente de `open` a `investigating` si comienzas a trabajar en ello inmediatamente. Siempre usa el estado más preciso para la situación actual. -Cada actualización de estado publica una respuesta en el hilo de la notificación original de Slack. +Cada actualización de estado publica una respuesta en el hilo de notificación original de Slack. -### Cerrar un incidente +### Cerrar un Incidente Para mover un incidente a `resolved` o `closed`, se debe establecer una **causa raíz**. Puedes establecer la causa raíz en cualquier etapa anterior si ya la conoces; se vuelve obligatoria al cerrar. @@ -164,12 +164,12 @@ Para mover un incidente a `resolved` o `closed`, se debe establecer una **causa | `configuration` | Cambio, corrección o reversión de configuración | | `capacity` | Congestión, límites de capacidad o gestión de tráfico | | `carrier` | Problema del proveedor de circuito, longitud de onda o cross-connect | -| `network_external` | Problema de red externa fuera del control del contribuidor | +| `network_external` | Problema de red externo fuera del control del contribuidor | | `facility` | Problema de infraestructura del centro de datos (energía, refrigeración) | | `fiber_cut` | Daño físico de fibra reparado | | `security` | Incidente de seguridad mitigado | | `human_error` | Error operativo corregido | -| `false_positive` | No se encontró ningún problema real tras la investigación | +| `false_positive` | No se encontró problema real después de la investigación | | `duplicate` | Ya registrado en otro ticket | | `self_resolved` | Problema resuelto sin intervención | | `dz_managed` | Problema con un componente de software gestionado por DoubleZero (activator, controller, etc.) | @@ -178,11 +178,11 @@ Para mover un incidente a `resolved` o `closed`, se debe establecer una **causa ## Mantenimiento -Un registro de mantenimiento es una actividad planificada y con tiempo limitado que puede afectar la disponibilidad. Créalo con antelación para que otros contribuidores puedan verlo y evitar ventanas conflictivas. +Un registro de mantenimiento es una actividad planificada y con tiempo delimitado que puede afectar la disponibilidad. Créalo con anticipación para que otros contribuidores puedan verlo y evitar ventanas conflictivas. -### Programar un mantenimiento +### Programar Mantenimiento -Haz clic en **Create New Record** > **Maintenance** en el portal, o envía a través de la API. +Haz clic en **Create New Record** > **Maintenance** en el portal, o envíalo a través de la API. **Obligatorio:** @@ -190,15 +190,18 @@ Haz clic en **Create New Record** > **Maintenance** en el portal, o envía a tra |-------|-------------| | `title` | Resumen breve (máximo 100 caracteres) | | `description` | Explicación detallada (máximo 500 caracteres) | +| `severity` | `sev1`, `sev2`, o `sev3`. Establécelo según el impacto esperado en los usuarios (ver nota abajo). | | `start_at` | Hora de inicio planificada (UTC) | | `end_at` | Hora de fin planificada (UTC); debe ser posterior a `start_at` | -| Dispositivo y/o Enlace | Al menos uno obligatorio. En el formulario web, selecciona de un desplegable con los códigos de tus dispositivos y enlaces. Al usar la API, pasa las pubkeys correspondientes como `device_pubkey` y/o `affected_link_pubkey`. | +| Dispositivo y/o Enlace | Se requiere al menos uno. En el formulario web, selecciona desde un menú desplegable de tus códigos de dispositivo y enlace. Al usar la API, pasa las claves públicas correspondientes como `device_pubkey` y/o `affected_link_pubkey`. | -Una vez creado, se publica una notificación en el canal de Slack de mantenimiento de contribuidores con el ID del ticket, los dispositivos/enlaces afectados, la ventana planificada y el nombre del contribuidor. +La severidad se aplica al mantenimiento de la misma manera que a los incidentes. Establécela según el impacto en los usuarios que esperas durante la ventana, usando los [niveles de severidad anteriores](#niveles-de-severidad). -### Gestionar el estado del mantenimiento +Una vez creado, se publica una notificación en el canal de Slack de mantenimiento de contribuidores con el ID del ticket, dispositivos/enlaces afectados, ventana planificada y nombre del contribuidor. -Mantén el estado actualizado a medida que la ventana progresa. +### Gestionar el Estado del Mantenimiento + +Mantén el estado actualizado a medida que avanza la ventana. | Estado | Cuándo establecerlo | |--------|----------------| @@ -216,13 +219,13 @@ planned → in-progress → completed → closed (auto 24h after end_at) --- -## Contactos de escalación +## Contactos de Escalación -Los contactos de escalación indican a DoubleZero y a otros contribuidores a quién contactar cuando tu parte de la red tiene un problema. Tú configuras tus propios contactos para tu organización. Un contacto puede ser una persona o un equipo, como tu NOC. Cada contacto tiene una o más formas de contactarlo y un horario de cuándo está de guardia. +Los contactos de escalación le indican a DoubleZero y a otros contribuidores a quién contactar cuando tu parte de la red tiene un problema. Tú configuras tus propios contactos para tu organización. Un contacto puede ser una persona o un equipo, como tu NOC. Cada contacto tiene una o más formas de comunicarse y un horario de cuándo está de guardia. -Abre el menú **Settings** (icono de engranaje) y elige **Escalation Contacts**. Solo los ops managers pueden añadir o editar contactos. +Abre el menú **Settings** (ícono de engranaje) y elige **Escalation Contacts**. Solo los ops managers pueden agregar o editar contactos. -### Añadir un contacto +### Agregar un Contacto Para cada contacto, establece: @@ -231,17 +234,17 @@ Para cada contacto, establece: | Nombre | Un nombre para el contacto, ya sea una persona o un equipo como tu NOC | | Zona horaria | La zona horaria local, utilizada para leer el horario | | Disponibilidad | **24/7**, o uno o más intervalos semanales cuando el contacto está de guardia | -| Métodos de contacto | Una o más formas de contactar, en orden de prioridad | +| Métodos de contacto | Una o más formas de contactar al contacto, en orden de prioridad | -Los métodos de contacto admitidos son email, teléfono, Slack, Telegram y WhatsApp. El orden importa: el primer método es el que se debe intentar primero. +Los métodos de contacto soportados son email, teléfono, Slack, Telegram y WhatsApp. El orden importa: el primer método es el que se debe intentar primero. -### Disponibilidad y brechas de cobertura +### Disponibilidad y Brechas de Cobertura -Un contacto está disponible las 24 horas del día (24/7) o disponible durante intervalos semanales que defines, por ejemplo de lunes a viernes, de 09:00 a 17:00. Los intervalos se introducen en la zona horaria local del contacto y se muestran en UTC, por lo que el horario de verano se gestiona automáticamente. +Un contacto está disponible las 24 horas (24/7) o disponible durante intervalos semanales que tú defines, por ejemplo de lunes a viernes, de 09:00 a 17:00. Los intervalos se ingresan en la zona horaria local del contacto y se muestran en UTC, por lo que el horario de verano se gestiona automáticamente. -La vista de **brechas de cobertura** muestra los momentos de cada semana en los que nadie de tu organización está de guardia. Úsala para encontrar y cerrar brechas. +La vista de **brechas de cobertura** muestra los horarios de cada semana en los que nadie de tu organización está de guardia. Úsala para encontrar y cerrar brechas. -### Ventanas de rotación +### Ventanas de Rotación La semana se divide en ventanas de media hora. Para cada ventana puedes establecer el orden en que se contacta a tus contactos. Esto te permite ejecutar una rotación de guardia sin editar cada contacto. @@ -251,7 +254,7 @@ Tú controlas quién puede ver tus contactos. DoubleZero siempre puede verlos. T | Configuración | Quién más puede ver tus contactos | |---------|-------------------------------| -| Solo DoubleZero (por defecto) | Ningún otro contribuidor | +| Solo DoubleZero (predeterminado) | Ningún otro contribuidor | | Todos | Todos los contribuidores | | Algunos contribuidores | Solo los contribuidores que selecciones | @@ -259,18 +262,18 @@ Tu propio equipo siempre puede ver tus contactos. La visibilidad se configura un --- -## Gestión de usuarios +## Gestión de Usuarios -Por defecto, tu clave de Ops Manager es la única cuenta que puede actuar en nombre de tu organización. Puedes añadir miembros del equipo para que más de una persona pueda gestionar tus tickets. +Por defecto, tu clave de Ops Manager es la única cuenta que puede actuar en nombre de tu organización. Puedes agregar miembros del equipo para que más de una persona pueda gestionar tus tickets. -Abre el menú **Settings** (icono de engranaje) y elige **User Management**. Solo los ops managers pueden añadir o eliminar miembros del equipo. +Abre el menú **Settings** (ícono de engranaje) y elige **User Management**. Solo los ops managers pueden agregar o eliminar miembros del equipo. Para cada miembro del equipo, establece: | Campo | Descripción | |-------|-------------| | Nombre | El nombre de la persona | -| Pubkey de wallet | La wallet de Solana con la que inician sesión | +| Clave pública de billetera | La billetera Solana con la que inicia sesión | | Nivel de acceso | **Read** o **Read-write** | Niveles de acceso: @@ -278,27 +281,27 @@ Niveles de acceso: - **Read**: puede ver tickets y contactos de escalación, y crear claves API de solo lectura. No puede crear, actualizar ni cerrar tickets. - **Read-write**: acceso completo para crear, actualizar y cerrar tickets, y puede crear claves API de cualquier nivel. -Cada miembro del equipo inicia sesión con su propia wallet, de la misma manera que conectaste tu clave de Ops Manager. +Cada miembro del equipo inicia sesión con su propia billetera, de la misma manera que conectaste tu clave de Ops Manager. --- -## Permisos y escalación +## Permisos y Escalación -### Qué pueden hacer los contribuidores +### Qué Pueden Hacer los Contribuidores - Crear y gestionar tickets solo para sus propios dispositivos y enlaces. - Asignar tickets a sí mismos o escalar a DZ/Malbeclabs. - Ver todos los tickets de todos los contribuidores. -- Añadir miembros del equipo y establecer su nivel de acceso (solo ops managers). +- Agregar miembros del equipo y establecer su nivel de acceso (solo ops managers). - Gestionar contactos de escalación para su organización (solo ops managers). -### Qué pueden hacer los administradores de DZ/Malbeclabs +### Qué Pueden Hacer los Administradores de DZ/Malbeclabs -- Crear tickets para los dispositivos y enlaces de cualquier contribuidor. +- Crear tickets para dispositivos y enlaces de cualquier contribuidor. - Asignar o reasignar tickets entre contribuidores. -- Gestionar escalaciones y solicitudes de soporte. +- Manejar escalaciones y solicitudes de soporte. -### Propiedad de enlaces DZX +### Propiedad de Enlaces DZX Los enlaces DZX conectan dispositivos de dos contribuidores diferentes. El contribuidor del **lado A** (primer dispositivo en el nombre del enlace) es el propietario del enlace y es el único que puede crear tickets para él. @@ -310,4 +313,4 @@ Los enlaces DZX conectan dispositivos de dos contribuidores diferentes. El contr 2. Asigna el ticket a DZ/Malbeclabs. 3. DZ/Malbeclabs investiga y reasigna al contribuidor del lado Z si es necesario. -Reconocemos que este flujo de trabajo es limitado. Los contribuidores del lado Z actualmente no pueden crear tickets para enlaces DZX que no poseen, lo que significa que la coordinación tiene que pasar por DZ/Malbeclabs. Estamos trabajando para mejorar esto de modo que ambos lados de un enlace DZX puedan declarar incidentes y mantenimientos de forma independiente. \ No newline at end of file +Reconocemos que este flujo de trabajo es limitado. Actualmente, los contribuidores del lado Z no pueden crear tickets para enlaces DZX que no poseen, lo que significa que la coordinación debe pasar a través de DZ/Malbeclabs. Estamos trabajando para mejorar esto de modo que ambos lados de un enlace DZX puedan declarar incidentes y mantenimientos de forma independiente. \ No newline at end of file diff --git a/docs/contribute-ops-management.fr.md b/docs/contribute-ops-management.fr.md index 556680a..7f5578f 100644 --- a/docs/contribute-ops-management.fr.md +++ b/docs/contribute-ops-management.fr.md @@ -1,23 +1,23 @@ # Gestion OPS -Le portail de gestion OPS de DoubleZero est l'endroit où les contributeurs enregistrent et suivent les incidents (pannes imprévues) et les maintenances (travaux planifiés) sur l'ensemble du réseau. Tous les tickets sont visibles par tous les contributeurs. +Le portail de Gestion OPS de DoubleZero est l'endroit où les contributeurs enregistrent et suivent les incidents (pannes imprévues) et les maintenances (travaux planifiés) sur l'ensemble du réseau. Tous les tickets sont visibles par tous les contributeurs. **Portail :** [https://doublezero.xyz/ops-management](https://doublezero.xyz/ops-management) ## Portail vs Slack -Le portail de gestion OPS et Slack fonctionnent ensemble. Tous les incidents et maintenances sont suivis sous forme de tickets, accessibles via le portail ou l'API. Chaque ticket notifie automatiquement les bons canaux Slack et offre à chaque contributeur une vue partagée de ce qui se passe sur le réseau. Slack est l'endroit où la conversation se déroule : partager des logs, se coordonner avec d'autres contributeurs et collaborer sur les problèmes en cours. +Le portail de Gestion OPS et Slack fonctionnent ensemble. Tous les incidents et maintenances sont suivis sous forme de tickets, accessibles via le portail ou l'API. Chaque ticket notifie automatiquement les bons canaux Slack et offre à chaque contributeur une vue partagée de ce qui se passe sur le réseau. Slack est l'endroit où la conversation a lieu : partager des logs, coordonner avec d'autres contributeurs et collaborer sur les problèmes en cours. -Les tickets constituent l'enregistrement de référence, qu'ils soient créés via le portail ou l'API. Les fils Slack ne le sont pas : ils ne mettent pas à jour le statut des tickets et ne sont pas stockés de manière permanente. Gardez toujours le statut du ticket à jour, même si la conversation se déroule dans Slack. +Les tickets sont l'enregistrement de référence, qu'ils soient créés via le portail ou l'API. Les fils Slack ne le sont pas : ils ne mettent pas à jour le statut des tickets et ne sont pas stockés de manière permanente. Gardez toujours le statut du ticket à jour, même si la conversation se déroule sur Slack. Le portail et Slack servent des objectifs différents. Utilisez les deux, mais pour les bonnes choses. | Utilisez le portail (ou l'API) pour... | Utilisez Slack pour... | |-------------------------------|-----------------| -| Ouvrir, mettre à jour et fermer des tickets | La conversation et la collaboration sur un problème en cours | -| Enregistrer les transitions de statut | Partager des logs, des captures d'écran ou lancer un appel | +| Ouvrir, mettre à jour et fermer des tickets | Conversation et collaboration sur un problème en cours | +| Enregistrer les transitions de statut | Partager des logs, des captures d'écran ou démarrer un appel | | Assigner ou escalader un ticket | Attirer rapidement l'attention sur un problème | -| Définir la cause racine à la clôture | Se coordonner avec d'autres contributeurs | +| Définir la cause racine à la clôture | Coordonner avec d'autres contributeurs | @@ -41,17 +41,17 @@ doublezero contributor update \ 1. Accédez à [https://doublezero.xyz/ops-management](https://doublezero.xyz/ops-management). 2. Cliquez sur **Connect Your Wallet** et sélectionnez votre portefeuille. -3. Signez le message pour prouver que vous êtes propriétaire de votre clé Ops Manager. +3. Signez le message pour prouver la propriété de votre clé Ops Manager. -Une fois authentifié, le **tableau de suivi des incidents** s'affiche. +Une fois authentifié, le **Tableau de suivi des incidents** s'affiche. -Les paramètres du compte se trouvent derrière le menu **Settings** (l'icône d'engrenage, en haut à droite) : gestion des clés API, gestion des utilisateurs et contacts d'escalade. Les options affichées dépendent de votre rôle. +Les paramètres du compte se trouvent dans le menu **Settings** (l'icône en forme d'engrenage, en haut à droite) : API Key Management, User Management et Escalation Contacts. Les options visibles dépendent de votre rôle. -### 3. Créer des clés API (optionnel) +### 3. Créer des clés API (Optionnel) Pour un accès programmatique au lieu du formulaire web : -1. Ouvrez le menu **Settings** (icône d'engrenage) et choisissez **API Key Management**. +1. Ouvrez le menu **Settings** (icône en forme d'engrenage) et choisissez **API Key Management**. 2. Créez une ou plusieurs clés API. 3. Téléchargez la documentation de l'API depuis cette page. @@ -59,52 +59,52 @@ Pour un accès programmatique au lieu du formulaire web : ## Incidents -Un incident est un événement imprévu impactant le service. +Un incident est un événement imprévu ayant un impact sur le service. ### Niveaux de sévérité -Attribuez la sévérité en fonction de l'impact sur le réseau DoubleZero. Vous pouvez mettre à jour la sévérité au fur et à mesure de l'évolution de la situation. +Attribuez la sévérité en fonction de l'impact sur le réseau DoubleZero. Vous pouvez mettre à jour la sévérité à mesure que la situation évolue. | Sévérité | Impact | Réponse | |----------|--------|----------| -| `sev1` | Panne complète ou rupture majeure du plan de contrôle/données sans solution de repli | Tout lâcher immédiatement, même en dehors des heures de travail. Escalader immédiatement à la DoubleZero Foundation. | -| `sev2` | Impact partiel mais substantiel ; service dégradé avec solution de repli possible | Traiter comme urgent. Coordonner activement. Réponse nocturne requise en cas de dégradation prolongée. | -| `sev3` | Impact limité ou non visible par l'utilisateur ; potentiel d'escalade si non résolu | Priorité absolue pendant les heures de travail. Surveiller attentivement. Aucune escalade en dehors des heures requise sauf si l'impact augmente. | +| `sev1` | Panne totale ou rupture majeure du plan de contrôle/données sans solution de repli | Tout arrêter immédiatement, même en dehors des heures de travail. Escalader immédiatement à la DoubleZero Foundation. | +| `sev2` | Impact partiel mais substantiel ; service dégradé avec solution de repli possible | Traiter comme urgent. Coordonner activement. Réponse de nuit requise en cas de dégradation prolongée. | +| `sev3` | Impact limité ou non visible pour l'utilisateur ; potentiel d'escalade si non résolu | Priorité absolue pendant les heures de travail. Surveiller de près. Pas d'escalade en dehors des heures sauf si l'impact augmente. | ??? note "Exemples de sévérité" **Exemples Sev1** - - Plus de 10 % du trafic utilisateur perdu (blackholed) sur DoubleZero, sans repli vers l'internet public - - Plus de 80 % des tentatives d'intégration, de connexion ou de déconnexion des utilisateurs en échec + - Plus de 10 % du trafic utilisateur perdu sur DoubleZero, sans repli vers l'internet public + - Plus de 80 % des tentatives d'inscription, connexion ou déconnexion utilisateur en échec - Plus de 20 % des DZD signalant des erreurs d'interface - - Le contrôleur renvoyant des configurations valides mais incorrectes aux agents DZD + - Le contrôleur retournant des configurations valides mais incorrectes aux agents DZD **Exemples Sev2** - Plus de 20 % des utilisateurs incapables d'envoyer/recevoir du trafic via les tunnels DoubleZero, mais avec repli vers l'internet public - - 0 à 10 % du trafic utilisateur perdu (blackholed) sur DoubleZero sans repli - - 20 à 80 % des nouvelles tentatives d'intégration, de connexion ou de déconnexion des utilisateurs en échec + - 0–10 % du trafic utilisateur perdu sur DoubleZero sans repli + - 20–80 % des tentatives d'inscription, connexion ou déconnexion de nouveaux utilisateurs en échec - Plus de 20 % des agents de configuration échouant à appliquer la configuration DZD - - 0 à 20 % des DZD signalant des erreurs d'interface - - Problèmes en amont causant une perte d'observabilité (monitoring/alerting en panne) + - 0–20 % des DZD signalant des erreurs d'interface + - Problèmes en amont causant une perte d'observabilité (monitoring/alertes en panne) - Pipeline de données onchain en panne ou produisant des données incorrectes - Plus de 20 % de la collecte ou soumission de latence internet en échec - Contrôleur inaccessible par les agents DZD - - Contrôleur renvoyant des configurations invalides aux DZD qui ne seront pas appliquées + - Contrôleur retournant des configurations invalides aux DZD qui ne seront pas appliquées **Exemples Sev3** - - 0 à 20 % des utilisateurs incapables d'envoyer/recevoir du trafic via les tunnels DoubleZero, avec repli vers l'internet public - - 0 à 20 % des DZD signalant des erreurs d'interface - - 0 à 20 % des DZD rencontrant des échecs d'agent de configuration - - 0 à 20 % des tentatives d'intégration, de connexion ou de déconnexion des utilisateurs en échec + - 0–20 % des utilisateurs incapables d'envoyer/recevoir du trafic via les tunnels DoubleZero, avec repli vers l'internet public + - 0–20 % des DZD signalant des erreurs d'interface + - 0–20 % des DZD rencontrant des échecs d'agent de configuration + - 0–20 % des tentatives d'inscription, connexion ou déconnexion utilisateur en échec - Plus de 20 % de la collecte ou soumission de latence internet en échec pour un seul fournisseur de données - - 0 à 20 % de la collecte ou soumission de latence internet en échec pour tous les fournisseurs de données - - Bugs ou dette technique causant du bruit d'alerte qui ne peut pas être réduit au silence - - DIA en panne ou problèmes réseau de ledger RPC pour 0 à 20 % des appareils pendant plusieurs heures + - 0–20 % de la collecte ou soumission de latence internet en échec pour tous les fournisseurs de données + - Bugs ou dette technique causant du bruit d'alertes qui ne peut pas être réduit au silence + - DIA en panne ou problèmes réseau RPC du ledger pour 0–20 % des appareils pendant plusieurs heures - Problèmes à faible impact tels que bugs mineurs, erreurs cosmétiques ou incidents isolés n'affectant pas le trafic client - - Petite fraction d'appareils signalant des erreurs de manière intermittente sans perturbation du service + - Petite fraction d'appareils signalant des erreurs de manière intermittente sans interruption de service ### Ouvrir un incident @@ -117,17 +117,17 @@ Cliquez sur **Create New Record**, sélectionnez Type = **Incident** sur le port | `title` | Résumé court (100 caractères maximum) | | `description` | Explication détaillée (500 caractères maximum) | | `severity` | `sev1`, `sev2` ou `sev3` | -| `status` | Ne peut pas être défini à un état terminal (`resolved`, `closed`) à la création | -| Appareil et/ou Lien | Au moins un requis. Sur le formulaire web, sélectionnez depuis un menu déroulant de vos codes d'appareils et de liens. En utilisant l'API, passez les clés publiques correspondantes en tant que `device_pubkey` et/ou `affected_link_pubkey`. | +| `status` | Ne peut pas être défini sur un état terminal (`resolved`, `closed`) à la création | +| Appareil et/ou Lien | Au moins un requis. Sur le formulaire web, sélectionnez depuis un menu déroulant de vos codes d'appareils et de liens. Lors de l'utilisation de l'API, passez les clés publiques correspondantes comme `device_pubkey` et/ou `affected_link_pubkey`. | **Optionnel :** | Champ | Description | |-------|-------------| | `reporter_name` / `reporter_email` | Vos coordonnées | -| `assignee` | Qui est responsable de la résolution | +| `assignee` | La personne responsable de la résolution | | `internal_reference` | Votre ID de ticket interne (ex. Jira, ServiceNow) | -| `start_at` | Par défaut à l'heure de création ; modifiable | +| `start_at` | Par défaut l'heure de création ; modifiable | Une fois créé, une notification est publiée dans le canal Slack des incidents contributeurs avec l'ID du ticket, la sévérité, les appareils/liens affectés et le nom du contributeur. @@ -139,10 +139,10 @@ Au fur et à mesure de l'évolution de l'incident, maintenez le statut du ticket |--------|----------------| | `open` | État initial : problème signalé, pas encore en cours de traitement | | `acknowledged` | Vous l'avez vu et en avez pris la responsabilité | -| `investigating` | Diagnostic actif : collecte de logs, vérification des métriques | +| `investigating` | Diagnostic actif en cours : collecte de logs, vérification des métriques | | `mitigating` | Cause racine connue ou suspectée ; application d'un correctif ou d'une solution de contournement | | `monitoring` | Correctif appliqué ; surveillance pour confirmer qu'il tient | -| `resolved` | Problème confirmé résolu ; **cause racine requise** | +| `resolved` | Problème confirmé comme résolu ; **cause racine requise** | | `closed` | Entièrement terminé ; aucune action supplémentaire ; **cause racine requise** | ``` @@ -151,7 +151,7 @@ open → acknowledged → investigating → mitigating → monitoring → resolv Vous pouvez sauter des statuts si c'est approprié. Par exemple, passer directement de `open` à `investigating` si vous commencez immédiatement à travailler dessus. Utilisez toujours le statut le plus précis pour l'état actuel. -Chaque mise à jour de statut publie une réponse dans le fil de notification Slack original. +Chaque mise à jour de statut publie une réponse dans le fil de la notification Slack d'origine. ### Clôturer un incident @@ -160,10 +160,10 @@ Pour faire passer un incident à `resolved` ou `closed`, une **cause racine** do | Code | Description | |------|-------------| | `hardware` | Réparation, remplacement ou mise à niveau matérielle (SFP, NIC, câble, appareil) | -| `software` | Correctif, mise à jour ou redémarrage logiciel ou firmware | -| `configuration` | Changement, correction ou rollback de configuration | +| `software` | Correctif, mise à jour ou redémarrage logiciel/firmware | +| `configuration` | Modification, correction ou restauration de configuration | | `capacity` | Congestion, limites de capacité ou gestion du trafic | -| `carrier` | Problème de circuit, longueur d'onde ou fournisseur de cross-connect | +| `carrier` | Problème de circuit, longueur d'onde ou fournisseur de brassage | | `network_external` | Problème réseau externe hors du contrôle du contributeur | | `facility` | Problème d'infrastructure du datacenter (alimentation, refroidissement) | | `fiber_cut` | Dommage physique de fibre réparé | @@ -172,13 +172,13 @@ Pour faire passer un incident à `resolved` ou `closed`, une **cause racine** do | `false_positive` | Aucun problème réel trouvé après investigation | | `duplicate` | Déjà suivi dans un autre ticket | | `self_resolved` | Problème résolu sans intervention | -| `dz_managed` | Problème avec un composant logiciel géré par DoubleZero (activator, controller, etc.) | +| `dz_managed` | Problème avec un composant logiciel géré par DoubleZero (activateur, contrôleur, etc.) | --- ## Maintenance -Un enregistrement de maintenance est une activité planifiée, limitée dans le temps, pouvant affecter la disponibilité. Créez-le à l'avance afin que les autres contributeurs puissent le voir et éviter les fenêtres conflictuelles. +Un enregistrement de maintenance est une activité planifiée, limitée dans le temps, pouvant affecter la disponibilité. Créez-le à l'avance pour que les autres contributeurs puissent le voir et éviter les fenêtres conflictuelles. ### Planifier une maintenance @@ -190,21 +190,24 @@ Cliquez sur **Create New Record** > **Maintenance** sur le portail, ou soumettez |-------|-------------| | `title` | Résumé court (100 caractères maximum) | | `description` | Explication détaillée (500 caractères maximum) | +| `severity` | `sev1`, `sev2` ou `sev3`. Définissez-la selon l'impact utilisateur attendu (voir la note ci-dessous). | | `start_at` | Heure de début prévue (UTC) | | `end_at` | Heure de fin prévue (UTC) ; doit être postérieure à `start_at` | -| Appareil et/ou Lien | Au moins un requis. Sur le formulaire web, sélectionnez depuis un menu déroulant de vos codes d'appareils et de liens. En utilisant l'API, passez les clés publiques correspondantes en tant que `device_pubkey` et/ou `affected_link_pubkey`. | +| Appareil et/ou Lien | Au moins un requis. Sur le formulaire web, sélectionnez depuis un menu déroulant de vos codes d'appareils et de liens. Lors de l'utilisation de l'API, passez les clés publiques correspondantes comme `device_pubkey` et/ou `affected_link_pubkey`. | + +La sévérité s'applique à la maintenance de la même manière qu'aux incidents. Définissez-la selon l'impact utilisateur que vous attendez pendant la fenêtre, en utilisant les [niveaux de sévérité ci-dessus](#niveaux-de-severite). Une fois créé, une notification est publiée dans le canal Slack de maintenance des contributeurs avec l'ID du ticket, les appareils/liens affectés, la fenêtre prévue et le nom du contributeur. ### Gérer le statut de maintenance -Maintenez le statut à jour au fur et à mesure de l'avancement de la fenêtre. +Maintenez le statut à jour au fur et à mesure de la progression de la fenêtre. | Statut | Quand le définir | |--------|----------------| | `planned` | Planifié, pas encore commencé | -| `in-progress` | Les travaux ont commencé | -| `completed` | Travaux terminés avec succès | +| `in-progress` | Le travail a commencé | +| `completed` | Travail terminé avec succès | | `closed` | Défini automatiquement 24 heures après `end_at` | | `cancelled` | Annulé avant ou pendant l'exécution | @@ -220,7 +223,7 @@ planned → in-progress → completed → closed (auto 24h après end_at) Les contacts d'escalade indiquent à DoubleZero et aux autres contributeurs qui contacter lorsque votre partie du réseau rencontre un problème. Vous configurez vos propres contacts pour votre organisation. Un contact peut être une personne ou une équipe, comme votre NOC. Chaque contact dispose d'un ou plusieurs moyens de le joindre et d'un planning indiquant quand il est d'astreinte. -Ouvrez le menu **Settings** (icône d'engrenage) et choisissez **Escalation Contacts**. Seuls les ops managers peuvent ajouter ou modifier des contacts. +Ouvrez le menu **Settings** (icône en forme d'engrenage) et choisissez **Escalation Contacts**. Seuls les ops managers peuvent ajouter ou modifier des contacts. ### Ajouter un contact @@ -233,17 +236,17 @@ Pour chaque contact, définissez : | Disponibilité | **24/7**, ou un ou plusieurs créneaux hebdomadaires pendant lesquels le contact est d'astreinte | | Méthodes de contact | Un ou plusieurs moyens de joindre le contact, par ordre de priorité | -Les méthodes de contact prises en charge sont l'email, le téléphone, Slack, Telegram et WhatsApp. L'ordre est important : la première méthode est celle à essayer en premier. +Les méthodes de contact prises en charge sont email, téléphone, Slack, Telegram et WhatsApp. L'ordre est important : la première méthode est celle à essayer en premier. ### Disponibilité et lacunes de couverture -Un contact est soit disponible en permanence (24/7), soit disponible pendant des créneaux hebdomadaires que vous définissez, par exemple du lundi au vendredi, de 09h00 à 17h00. Les créneaux sont saisis dans le fuseau horaire local du contact et affichés en UTC, de sorte que l'heure d'été est gérée pour vous. +Un contact est soit disponible en permanence (24/7), soit disponible pendant des créneaux hebdomadaires que vous définissez, par exemple du lundi au vendredi, de 09h00 à 17h00. Les créneaux sont saisis dans le fuseau horaire local du contact et affichés en UTC, de sorte que le changement d'heure est géré pour vous. -La vue **lacunes de couverture** montre les moments de chaque semaine où personne de votre organisation n'est d'astreinte. Utilisez-la pour identifier et combler les lacunes. +La vue **coverage gaps** (lacunes de couverture) montre les moments de chaque semaine où personne de votre organisation n'est d'astreinte. Utilisez-la pour identifier et combler les lacunes. ### Fenêtres de rotation -La semaine est divisée en créneaux de trente minutes. Pour chaque créneau, vous pouvez définir l'ordre dans lequel vos contacts sont sollicités. Cela vous permet de gérer une rotation d'astreinte sans modifier chaque contact individuellement. +La semaine est divisée en fenêtres d'une demi-heure. Pour chaque fenêtre, vous pouvez définir l'ordre dans lequel vos contacts sont sollicités. Cela vous permet de mettre en place une rotation d'astreinte sans modifier chaque contact. ### Visibilité @@ -261,9 +264,9 @@ Votre propre équipe peut toujours voir vos contacts. La visibilité est défini ## Gestion des utilisateurs -Par défaut, votre clé Ops Manager est le seul compte pouvant agir au nom de votre organisation. Vous pouvez ajouter des membres d'équipe afin que plusieurs personnes puissent gérer vos tickets. +Par défaut, votre clé Ops Manager est le seul compte pouvant agir pour votre organisation. Vous pouvez ajouter des membres d'équipe pour que plusieurs personnes puissent gérer vos tickets. -Ouvrez le menu **Settings** (icône d'engrenage) et choisissez **User Management**. Seuls les ops managers peuvent ajouter ou supprimer des membres d'équipe. +Ouvrez le menu **Settings** (icône en forme d'engrenage) et choisissez **User Management**. Seuls les ops managers peuvent ajouter ou supprimer des membres d'équipe. Pour chaque membre d'équipe, définissez : @@ -275,8 +278,8 @@ Pour chaque membre d'équipe, définissez : Niveaux d'accès : -- **Lecture** : peut consulter les tickets et les contacts d'escalade, et créer des clés API en lecture seule. Ne peut pas créer, mettre à jour ou fermer des tickets. -- **Lecture-écriture** : accès complet pour créer, mettre à jour et fermer des tickets, et peut créer des clés API de tout niveau. +- **Lecture** : peut consulter les tickets et les contacts d'escalade, et créer des clés API en lecture seule. Ne peut pas créer, mettre à jour ou clôturer des tickets. +- **Lecture-écriture** : accès complet pour créer, mettre à jour et clôturer des tickets, et peut créer des clés API de tout niveau. Chaque membre d'équipe se connecte avec son propre portefeuille, de la même manière que vous avez connecté votre clé Ops Manager. @@ -286,9 +289,9 @@ Chaque membre d'équipe se connecte avec son propre portefeuille, de la même ma ### Ce que les contributeurs peuvent faire -- Créer et gérer des tickets pour leurs propres appareils et liens uniquement. -- S'assigner des tickets ou escalader vers DZ/Malbeclabs. -- Voir tous les tickets de tous les contributeurs. +- Créer et gérer des tickets uniquement pour leurs propres appareils et liens. +- S'assigner des tickets ou les escalader à DZ/Malbeclabs. +- Consulter tous les tickets de tous les contributeurs. - Ajouter des membres d'équipe et définir leur niveau d'accès (ops managers uniquement). - Gérer les contacts d'escalade pour leur organisation (ops managers uniquement). @@ -304,7 +307,7 @@ Les liens DZX connectent des appareils de deux contributeurs différents. Le con **Exemple :** Pour le lien `deviceA:deviceB`, le contributeur propriétaire de `deviceA` est propriétaire du lien. -**Si le problème est côté Z :** +**Si le problème est du côté Z :** 1. Le contributeur côté A crée un ticket pour le lien DZX. 2. Assigne le ticket à DZ/Malbeclabs. diff --git a/docs/contribute-ops-management.it.md b/docs/contribute-ops-management.it.md index 22577c7..6687996 100644 --- a/docs/contribute-ops-management.it.md +++ b/docs/contribute-ops-management.it.md @@ -1,14 +1,14 @@ # Gestione OPS -Il portale di gestione OPS di DoubleZero è il luogo in cui i contributor registrano e tracciano gli incidenti (interruzioni non pianificate) e le manutenzioni (lavori pianificati) su tutta la rete. Tutti i ticket sono visibili a tutti i contributor. +Il portale di Gestione OPS di DoubleZero è il luogo in cui i contributor registrano e tracciano gli incidenti (interruzioni non pianificate) e le manutenzioni (lavori pianificati) su tutta la rete. Tutti i ticket sono visibili a tutti i contributor. **Portale:** [https://doublezero.xyz/ops-management](https://doublezero.xyz/ops-management) ## Portale vs Slack -Il portale di gestione OPS e Slack funzionano insieme. Tutti gli incidenti e le manutenzioni vengono tracciati come ticket, accessibili tramite il portale o l'API. Ogni ticket notifica automaticamente i canali Slack appropriati e offre a ogni contributor una visione condivisa di ciò che sta accadendo sulla rete. Slack è il luogo in cui avviene la conversazione: condivisione di log, coordinamento con altri contributor e collaborazione su problemi attivi. +Il portale di Gestione OPS e Slack lavorano insieme. Tutti gli incidenti e le manutenzioni sono tracciati come ticket, accessibili tramite il portale o l'API. Ogni ticket notifica automaticamente i canali Slack appropriati e offre a ogni contributor una visione condivisa di ciò che sta accadendo sulla rete. Slack è dove avviene la conversazione: condivisione di log, coordinamento con altri contributor e collaborazione su problemi attivi. -I ticket sono il registro ufficiale, sia che vengano creati tramite il portale o l'API. I thread di Slack no: non aggiornano lo stato del ticket e non vengono archiviati permanentemente. Mantieni sempre aggiornato lo stato del ticket, anche se la conversazione avviene su Slack. +I ticket sono il registro ufficiale, che siano creati tramite il portale o l'API. I thread di Slack no: non aggiornano lo stato del ticket e non vengono archiviati permanentemente. Mantieni sempre aggiornato lo stato del ticket, anche se la conversazione sta avvenendo su Slack. Il portale e Slack servono a scopi diversi. Usa entrambi, ma per le cose giuste. @@ -17,7 +17,7 @@ Il portale e Slack servono a scopi diversi. Usa entrambi, ma per le cose giuste. | Aprire, aggiornare e chiudere ticket | Conversazione e collaborazione su un problema attivo | | Registrare le transizioni di stato | Condividere log, screenshot o avviare una chiamata | | Assegnare o escalare un ticket | Attirare rapidamente l'attenzione su un problema | -| Impostare la causa radice alla chiusura | Coordinarsi con altri contributor | +| Impostare la causa radice alla chiusura | Coordinamento con altri contributor | @@ -25,11 +25,11 @@ Il portale e Slack servono a scopi diversi. Usa entrambi, ma per le cose giuste. ## Onboarding -Completa questi passaggi una volta prima di utilizzare il portale. +Completa questi passaggi una sola volta prima di utilizzare il portale. ### 1. Imposta la tua chiave Ops Manager -Registra una pubkey di un wallet Solana come chiave Ops Manager. Wallet supportati: Phantom, Solflare, Coinbase Wallet. +Registra una chiave pubblica di un wallet Solana come chiave Ops Manager. Wallet supportati: Phantom, Solflare, Coinbase Wallet. ```bash doublezero contributor update \ @@ -37,7 +37,7 @@ doublezero contributor update \ --pubkey ``` -### 2. Collega il tuo wallet sul portale +### 2. Connetti il tuo Wallet sul Portale 1. Vai su [https://doublezero.xyz/ops-management](https://doublezero.xyz/ops-management). 2. Clicca su **Connect Your Wallet** e seleziona il tuo wallet. @@ -45,11 +45,11 @@ doublezero contributor update \ Una volta autenticato, viene mostrata la **Tabella di Tracciamento Incidenti**. -Le impostazioni dell'account si trovano nel menu **Settings** (l'icona a ingranaggio, in alto a destra): API Key Management, User Management e Escalation Contacts. Le opzioni visibili dipendono dal tuo ruolo. +Le impostazioni dell'account si trovano nel menu **Settings** (l'icona a ingranaggio, in alto a destra): API Key Management, User Management e Escalation Contacts. Le opzioni visualizzate dipendono dal tuo ruolo. ### 3. Crea chiavi API (Opzionale) -Per l'accesso programmatico in alternativa al modulo web: +Per l'accesso programmatico invece del modulo web: 1. Apri il menu **Settings** (icona a ingranaggio) e scegli **API Key Management**. 2. Crea una o più chiavi API. @@ -59,7 +59,7 @@ Per l'accesso programmatico in alternativa al modulo web: ## Incidenti -Un incidente è un evento non pianificato che impatta il servizio. +Un incidente è un evento non pianificato che ha impatto sul servizio. ### Livelli di Severità @@ -67,95 +67,95 @@ Assegna la severità in base all'impatto sulla rete DoubleZero. Puoi aggiornare | Severità | Impatto | Risposta | |----------|---------|----------| -| `sev1` | Interruzione totale o grave malfunzionamento del piano di controllo/dati senza fallback | Lascia tutto immediatamente, anche fuori dall'orario di lavoro. Escala immediatamente alla DoubleZero Foundation. | -| `sev2` | Impatto parziale ma sostanziale; servizio degradato con possibile fallback | Tratta come urgente. Coordinati attivamente. Risposta notturna richiesta per degradazioni prolungate. | -| `sev3` | Impatto limitato o non visibile agli utenti; potenziale escalation se non risolto | Massima priorità durante l'orario di lavoro. Monitora attentamente. Nessuna escalation fuori orario richiesta a meno che l'impatto non aumenti. | +| `sev1` | Interruzione totale o rottura grave del piano di controllo/dati senza fallback | Lascia tutto immediatamente, anche fuori dall'orario di lavoro. Escala immediatamente alla DoubleZero Foundation. | +| `sev2` | Impatto parziale ma sostanziale; servizio degradato con possibile fallback | Tratta come urgente. Coordina attivamente. Risposta notturna richiesta per degradi prolungati. | +| `sev3` | Impatto limitato o non visibile all'utente; potenziale escalation se non risolto | Massima priorità durante l'orario di lavoro. Monitora attentamente. Nessuna escalation fuori orario richiesta a meno che l'impatto non aumenti. | ??? note "Esempi di severità" **Esempi Sev1** - - Più del 10% del traffico utente perso su DoubleZero, nessun fallback verso internet pubblico - - Più dell'80% dei tentativi di onboarding, connessione o disconnessione degli utenti falliti + - Più del 10% del traffico utente in blackhole su DoubleZero, senza fallback verso internet pubblico + - Più dell'80% dei tentativi di onboarding, connessione o disconnessione utente falliti - Più del 20% dei DZD che riportano errori di interfaccia - - Il controller restituisce configurazioni valide ma errate agli agenti DZD + - Controller che restituisce configurazioni valide ma errate agli agenti DZD **Esempi Sev2** - - Più del 20% degli utenti impossibilitati a inviare/ricevere traffico sui tunnel DoubleZero, ma con fallback verso internet pubblico - - 0–10% del traffico utente perso su DoubleZero senza fallback - - 20–80% dei nuovi tentativi di onboarding, connessione o disconnessione degli utenti falliti + - Più del 20% degli utenti impossibilitati a inviare/ricevere traffico tramite tunnel DoubleZero, ma con fallback verso internet pubblico + - 0–10% del traffico utente in blackhole su DoubleZero senza fallback + - 20–80% dei tentativi di onboarding, connessione o disconnessione di nuovi utenti falliti - Più del 20% degli agenti di configurazione che non riescono ad applicare la configurazione DZD - 0–20% dei DZD che riportano errori di interfaccia - Problemi upstream che causano perdita di osservabilità (monitoraggio/alerting non funzionanti) - Pipeline dati onchain non funzionante o che produce dati errati - Più del 20% della raccolta o invio di latenza internet falliti - - Controller irraggiungibile dagli agenti DZD + - Controller inaccessibile dagli agenti DZD - Controller che restituisce configurazioni non valide ai DZD che non verranno applicate **Esempi Sev3** - - 0–20% degli utenti impossibilitati a inviare/ricevere traffico sui tunnel DoubleZero, con fallback verso internet pubblico + - 0–20% degli utenti impossibilitati a inviare/ricevere traffico tramite tunnel DoubleZero, con fallback verso internet pubblico - 0–20% dei DZD che riportano errori di interfaccia - 0–20% dei DZD che riscontrano errori dell'agente di configurazione - - 0–20% dei tentativi di onboarding, connessione o disconnessione degli utenti falliti - - Più del 20% della raccolta o invio di latenza internet falliti per un singolo fornitore di dati - - 0–20% della raccolta o invio di latenza internet falliti per tutti i fornitori di dati - - Bug o debito tecnico che causa rumore negli alert che non può essere silenziato - - DIA non funzionante o problemi di rete RPC del ledger per 0–20% dei dispositivi per diverse ore - - Problemi a basso impatto come bug minori, errori estetici o incidenti isolati che non impattano il traffico dei clienti + - 0–20% dei tentativi di onboarding, connessione o disconnessione utente falliti + - Più del 20% della raccolta o invio di latenza internet falliti per un singolo data provider + - 0–20% della raccolta o invio di latenza internet falliti per tutti i data provider + - Bug o debito tecnico che causano rumore negli alert che non può essere silenziato + - DIA non funzionante o problemi di rete RPC del ledger per lo 0–20% dei dispositivi per diverse ore + - Problemi a basso impatto come bug minori, errori cosmetici o incidenti isolati che non influenzano il traffico dei clienti - Piccola frazione di dispositivi che riportano errori intermittenti senza interruzione del servizio ### Apertura di un Incidente -Clicca su **Create New Record**, seleziona Type = **Incident** sul portale, oppure invia tramite l'API. +Clicca **Create New Record**, seleziona Type = **Incident** sul portale, oppure invia tramite l'API. **Obbligatori:** | Campo | Descrizione | |-------|-------------| -| `title` | Breve riepilogo (max 100 caratteri) | -| `description` | Spiegazione dettagliata (max 500 caratteri) | +| `title` | Breve riepilogo (massimo 100 caratteri) | +| `description` | Spiegazione dettagliata (massimo 500 caratteri) | | `severity` | `sev1`, `sev2` o `sev3` | | `status` | Non può essere impostato su uno stato terminale (`resolved`, `closed`) alla creazione | -| Dispositivo e/o Link | Almeno uno obbligatorio. Nel modulo web, seleziona dal menu a tendina dei codici dei tuoi dispositivi e link. Quando usi l'API, passa le pubkey corrispondenti come `device_pubkey` e/o `affected_link_pubkey`. | +| Dispositivo e/o Link | Almeno uno obbligatorio. Nel modulo web, seleziona dal menu a tendina i codici dei tuoi dispositivi e link. Quando usi l'API, passa le pubkey corrispondenti come `device_pubkey` e/o `affected_link_pubkey`. | **Opzionali:** | Campo | Descrizione | |-------|-------------| -| `reporter_name` / `reporter_email` | I tuoi recapiti | +| `reporter_name` / `reporter_email` | I tuoi dati di contatto | | `assignee` | Chi è responsabile della risoluzione | | `internal_reference` | Il tuo ID ticket interno (es. Jira, ServiceNow) | -| `start_at` | Default all'ora di creazione; modificabile | +| `start_at` | Predefinito all'ora di creazione; modificabile | -Una volta creato, una notifica viene pubblicata nel canale Slack per gli incidenti dei contributor con l'ID del ticket, la severità, i dispositivi/link interessati e il nome del contributor. +Una volta creato, una notifica viene pubblicata nel canale Slack degli incidenti dei contributor con l'ID del ticket, la severità, i dispositivi/link interessati e il nome del contributor. ### Aggiornamento di un Incidente -Man mano che l'incidente progredisce, mantieni aggiornato lo stato del ticket. Questo è il segnale che altri contributor e DZ usano per capire su cosa si sta lavorando. +Man mano che l'incidente progredisce, mantieni aggiornato lo stato del ticket. Questo è il segnale che gli altri contributor e DZ utilizzano per capire su cosa si sta lavorando. | Stato | Quando impostarlo | |-------|-------------------| | `open` | Stato iniziale: problema segnalato, non ancora in lavorazione | -| `acknowledged` | L'hai visto e te ne sei preso carico | -| `investigating` | Diagnosi attiva: raccolta log, verifica metriche | +| `acknowledged` | L'hai visto e ne hai preso la responsabilità | +| `investigating` | Diagnosi attiva: raccolta di log, verifica delle metriche | | `mitigating` | Causa radice nota o sospettata; applicazione di una correzione o workaround | -| `monitoring` | Correzione applicata; monitoraggio per confermare che tiene | +| `monitoring` | Correzione applicata; monitoraggio per confermare che tenga | | `resolved` | Problema confermato come risolto; **causa radice obbligatoria** | -| `closed` | Completamente concluso; nessuna ulteriore azione; **causa radice obbligatoria** | +| `closed` | Completamente chiuso; nessuna ulteriore azione; **causa radice obbligatoria** | ``` open → acknowledged → investigating → mitigating → monitoring → resolved → closed ``` -Puoi saltare degli stati se appropriato. Ad esempio, passa direttamente da `open` a `investigating` se inizi a lavorarci immediatamente. Usa sempre lo stato più accurato per la situazione corrente. +Puoi saltare degli stati se appropriato. Ad esempio, passa direttamente da `open` a `investigating` se inizi subito a lavorarci. Usa sempre lo stato più accurato per la situazione corrente. Ogni aggiornamento di stato pubblica una risposta nel thread della notifica Slack originale. ### Chiusura di un Incidente -Per portare un incidente allo stato `resolved` o `closed`, è necessario impostare una **causa radice**. Puoi impostare la causa radice in qualsiasi fase precedente se la conosci già; diventa obbligatoria alla chiusura. +Per portare un incidente a `resolved` o `closed`, una **causa radice** deve essere impostata. Puoi impostare la causa radice in qualsiasi fase precedente se la conosci già; diventa obbligatoria alla chiusura. | Codice | Descrizione | |--------|-------------| @@ -169,7 +169,7 @@ Per portare un incidente allo stato `resolved` o `closed`, è necessario imposta | `fiber_cut` | Danno fisico alla fibra riparato | | `security` | Incidente di sicurezza mitigato | | `human_error` | Errore operativo corretto | -| `false_positive` | Nessun problema reale trovato dopo l'indagine | +| `false_positive` | Nessun problema reale riscontrato dopo l'indagine | | `duplicate` | Già tracciato in un altro ticket | | `self_resolved` | Problema risolto senza intervento | | `dz_managed` | Problema con un componente software gestito da DoubleZero (activator, controller, ecc.) | @@ -178,23 +178,26 @@ Per portare un incidente allo stato `resolved` o `closed`, è necessario imposta ## Manutenzione -Un record di manutenzione è un'attività pianificata e delimitata nel tempo che potrebbe influire sulla disponibilità. Crealo in anticipo così che altri contributor possano vederlo ed evitare finestre in conflitto. +Un record di manutenzione è un'attività pianificata, con durata limitata nel tempo, che potrebbe influire sulla disponibilità. Crealo in anticipo in modo che gli altri contributor possano vederlo ed evitare finestre in conflitto. ### Pianificazione della Manutenzione -Clicca su **Create New Record** > **Maintenance** sul portale, oppure invia tramite l'API. +Clicca **Create New Record** > **Maintenance** sul portale, oppure invia tramite l'API. **Obbligatori:** | Campo | Descrizione | |-------|-------------| -| `title` | Breve riepilogo (max 100 caratteri) | -| `description` | Spiegazione dettagliata (max 500 caratteri) | +| `title` | Breve riepilogo (massimo 100 caratteri) | +| `description` | Spiegazione dettagliata (massimo 500 caratteri) | +| `severity` | `sev1`, `sev2` o `sev3`. Impostala sull'impatto utente previsto (vedi nota sotto). | | `start_at` | Orario di inizio pianificato (UTC) | | `end_at` | Orario di fine pianificato (UTC); deve essere successivo a `start_at` | -| Dispositivo e/o Link | Almeno uno obbligatorio. Nel modulo web, seleziona dal menu a tendina dei codici dei tuoi dispositivi e link. Quando usi l'API, passa le pubkey corrispondenti come `device_pubkey` e/o `affected_link_pubkey`. | +| Dispositivo e/o Link | Almeno uno obbligatorio. Nel modulo web, seleziona dal menu a tendina i codici dei tuoi dispositivi e link. Quando usi l'API, passa le pubkey corrispondenti come `device_pubkey` e/o `affected_link_pubkey`. | -Una volta creato, una notifica viene pubblicata nel canale Slack per le manutenzioni dei contributor con l'ID del ticket, i dispositivi/link interessati, la finestra pianificata e il nome del contributor. +La severità si applica alla manutenzione nello stesso modo in cui si applica agli incidenti. Impostala sull'impatto utente che prevedi durante la finestra, utilizzando i [livelli di severità sopra indicati](#livelli-di-severità). + +Una volta creato, una notifica viene pubblicata nel canale Slack delle manutenzioni dei contributor con l'ID del ticket, i dispositivi/link interessati, la finestra pianificata e il nome del contributor. ### Gestione dello Stato della Manutenzione @@ -209,7 +212,7 @@ Mantieni aggiornato lo stato man mano che la finestra progredisce. | `cancelled` | Annullata prima o durante l'esecuzione | ``` -planned → in-progress → completed → closed (auto 24h after end_at) +planned → in-progress → completed → closed (auto 24h dopo end_at) ↓ ↓ └──────────┴──→ cancelled ``` @@ -218,7 +221,7 @@ planned → in-progress → completed → closed (auto 24h after end_at) ## Contatti di Escalation -I contatti di escalation indicano a DoubleZero e agli altri contributor chi contattare quando la tua parte della rete ha un problema. Configuri i tuoi contatti per la tua organizzazione. Un contatto può essere una persona o un team, come il tuo NOC. Ogni contatto ha uno o più modi per essere raggiunto e un orario di reperibilità. +I contatti di escalation indicano a DoubleZero e agli altri contributor chi contattare quando la tua parte della rete ha un problema. Configuri i tuoi contatti per la tua organizzazione. Un contatto può essere una persona o un team, come il tuo NOC. Ogni contatto ha uno o più modi per essere raggiunto e un programma per quando è reperibile. Apri il menu **Settings** (icona a ingranaggio) e scegli **Escalation Contacts**. Solo gli ops manager possono aggiungere o modificare i contatti. @@ -228,18 +231,18 @@ Per ogni contatto, imposta: | Campo | Descrizione | |-------|-------------| -| Name | Un nome per il contatto, sia esso una persona o un team come il tuo NOC | -| Timezone | Il fuso orario locale, utilizzato per leggere l'orario | -| Availability | **24/7**, oppure una o più fasce orarie settimanali in cui il contatto è reperibile | -| Contact methods | Uno o più modi per raggiungere il contatto, in ordine di priorità | +| Nome | Un nome per il contatto, che sia una persona o un team come il tuo NOC | +| Fuso orario | Il fuso orario locale, utilizzato per leggere il programma | +| Disponibilità | **24/7**, oppure una o più fasce orarie settimanali in cui il contatto è reperibile | +| Metodi di contatto | Uno o più modi per raggiungere il contatto, in ordine di priorità | I metodi di contatto supportati sono email, telefono, Slack, Telegram e WhatsApp. L'ordine è importante: il primo metodo è quello da provare per primo. -### Disponibilità e Gap di Copertura +### Disponibilità e Lacune di Copertura -Un contatto è disponibile 24 ore su 24, 7 giorni su 7, oppure durante fasce orarie settimanali che definisci, ad esempio dal lunedì al venerdì, dalle 09:00 alle 17:00. Le fasce vengono inserite nel fuso orario locale del contatto e visualizzate in UTC, quindi l'ora legale viene gestita automaticamente. +Un contatto è disponibile 24 ore su 24, 7 giorni su 7 (24/7) oppure disponibile durante fasce orarie settimanali che definisci tu, ad esempio dal lunedì al venerdì, dalle 09:00 alle 17:00. Le fasce vengono inserite nel fuso orario locale del contatto e mostrate in UTC, così l'ora legale viene gestita automaticamente. -La vista **coverage gaps** mostra i momenti della settimana in cui nessuno della tua organizzazione è reperibile. Usala per individuare e colmare i gap. +La vista **coverage gaps** mostra i momenti della settimana in cui nessuno della tua organizzazione è reperibile. Usala per trovare e colmare le lacune. ### Finestre di Rotazione @@ -247,10 +250,10 @@ La settimana è suddivisa in finestre di mezz'ora. Per ogni finestra puoi impost ### Visibilità -Controlli chi può vedere i tuoi contatti. DoubleZero può sempre vederli. Tu scegli chi altro può: +Controlli chi può vedere i tuoi contatti. DoubleZero può sempre vederli. Scegli tu chi altro può: | Impostazione | Chi altro può vedere i tuoi contatti | -|--------------|--------------------------------------| +|-------------|--------------------------------------| | Solo DoubleZero (predefinito) | Nessun altro contributor | | Tutti | Tutti i contributor | | Alcuni contributor | Solo i contributor che selezioni | @@ -269,22 +272,22 @@ Per ogni membro del team, imposta: | Campo | Descrizione | |-------|-------------| -| Name | Il nome della persona | +| Nome | Il nome della persona | | Wallet pubkey | Il wallet Solana con cui effettua l'accesso | -| Access level | **Read** o **Read-write** | +| Livello di accesso | **Read** o **Read-write** | Livelli di accesso: -- **Read**: può visualizzare ticket e contatti di escalation e creare chiavi API di sola lettura. Non può creare, aggiornare o chiudere ticket. +- **Read**: può visualizzare ticket e contatti di escalation, e creare chiavi API in sola lettura. Non può creare, aggiornare o chiudere ticket. - **Read-write**: accesso completo per creare, aggiornare e chiudere ticket, e può creare chiavi API di qualsiasi livello. -Ogni membro del team accede con il proprio wallet, nello stesso modo in cui hai collegato la tua chiave Ops Manager. +Ogni membro del team effettua l'accesso con il proprio wallet, nello stesso modo in cui hai connesso la tua chiave Ops Manager. --- ## Permessi ed Escalation -### Cosa possono fare i Contributor +### Cosa Possono Fare i Contributor - Creare e gestire ticket solo per i propri dispositivi e link. - Assegnare ticket a se stessi o escalare a DZ/Malbeclabs. @@ -292,7 +295,7 @@ Ogni membro del team accede con il proprio wallet, nello stesso modo in cui hai - Aggiungere membri del team e impostare il loro livello di accesso (solo ops manager). - Gestire i contatti di escalation per la propria organizzazione (solo ops manager). -### Cosa possono fare gli Admin DZ/Malbeclabs +### Cosa Possono Fare gli Admin DZ/Malbeclabs - Creare ticket per i dispositivi e link di qualsiasi contributor. - Assegnare o riassegnare ticket tra contributor. @@ -300,7 +303,7 @@ Ogni membro del team accede con il proprio wallet, nello stesso modo in cui hai ### Proprietà dei Link DZX -I link DZX collegano dispositivi di due contributor diversi. Il contributor **A-side** (primo dispositivo nel nome del link) è il proprietario del link ed è l'unico che può creare ticket per esso. +I link DZX connettono dispositivi di due contributor diversi. Il contributor **A-side** (primo dispositivo nel nome del link) è il proprietario del link ed è l'unico che può creare ticket per esso. **Esempio:** Per il link `deviceA:deviceB`, il contributor che possiede `deviceA` è il proprietario del link. @@ -310,4 +313,4 @@ I link DZX collegano dispositivi di due contributor diversi. Il contributor **A- 2. Assegna il ticket a DZ/Malbeclabs. 3. DZ/Malbeclabs indaga e riassegna al contributor Z-side se necessario. -Riconosciamo che questo flusso di lavoro è limitato. I contributor Z-side attualmente non possono creare ticket per link DZX di cui non sono proprietari, il che significa che il coordinamento deve passare attraverso DZ/Malbeclabs. Stiamo lavorando per migliorare questa situazione in modo che entrambi i lati di un link DZX possano dichiarare incidenti e manutenzioni in modo indipendente. \ No newline at end of file +Riconosciamo che questo flusso di lavoro è limitato. I contributor Z-side attualmente non possono creare ticket per i link DZX di cui non sono proprietari, il che significa che il coordinamento deve passare attraverso DZ/Malbeclabs. Stiamo lavorando per migliorare questa situazione in modo che entrambi i lati di un link DZX possano dichiarare incidenti e manutenzioni in modo indipendente. \ No newline at end of file diff --git a/docs/contribute-ops-management.ja.md b/docs/contribute-ops-management.ja.md index 8f24e7e..0a6af3c 100644 --- a/docs/contribute-ops-management.ja.md +++ b/docs/contribute-ops-management.ja.md @@ -1,20 +1,20 @@ # OPS管理 -DoubleZero OPS管理ポータルは、コントリビューターがネットワーク全体のインシデント（計画外の障害）とメンテナンス（計画作業）を記録・追跡する場所です。すべてのチケットはすべてのコントリビューターに公開されます。 +DoubleZero OPS管理ポータルは、コントリビューターがネットワーク全体のインシデント（計画外の障害）およびメンテナンス（計画的な作業）を記録・追跡する場所です。すべてのチケットはすべてのコントリビューターに公開されます。 **ポータル:** [https://doublezero.xyz/ops-management](https://doublezero.xyz/ops-management) ## ポータルとSlack -OPS管理ポータルとSlackは連携して機能します。すべてのインシデントとメンテナンスはチケットとして追跡され、ポータルまたはAPIからアクセスできます。各チケットは適切なSlackチャンネルに自動的に通知を送り、すべてのコントリビューターにネットワーク上で何が起きているかの共有ビューを提供します。Slackは会話が行われる場所です：ログの共有、他のコントリビューターとの調整、アクティブな問題に関するコラボレーションなど。 +OPS管理ポータルとSlackは連携して機能します。すべてのインシデントとメンテナンスはチケットとして追跡され、ポータルまたはAPIからアクセスできます。各チケットは適切なSlackチャンネルに自動通知を送り、すべてのコントリビューターにネットワーク上で何が起きているかの共有ビューを提供します。Slackは会話が行われる場所です：ログの共有、他のコントリビューターとの調整、アクティブな問題への協力などです。 -チケットは、ポータル経由で作成されたものもAPI経由で作成されたものも、正式な記録です。Slackスレッドはそうではありません：チケットのステータスを更新せず、永続的に保存されることもありません。会話がSlackで行われている場合でも、チケットのステータスを常に最新の状態に保ってください。 +チケットは、ポータル経由で作成されたかAPI経由で作成されたかにかかわらず、正式な記録です。Slackスレッドはそうではありません：チケットのステータスは更新されず、永続的に保存されません。会話がSlackで行われている場合でも、常にチケットのステータスを最新に保ってください。 -ポータルとSlackはそれぞれ異なる目的を持っています。両方を使用してください。ただし、適切な用途に使い分けてください。 +ポータルとSlackはそれぞれ異なる目的を果たします。両方を使用してください。ただし、適切な用途に使い分けてください。 | ポータル（またはAPI）で行うこと... | Slackで行うこと... | |-------------------------------|-----------------| -| チケットのオープン、更新、クローズ | アクティブな問題に関する会話とコラボレーション | +| チケットの作成、更新、クローズ | アクティブな問題に関する会話とコラボレーション | | ステータス遷移の記録 | ログやスクリーンショットの共有、通話の開始 | | チケットの割り当てまたはエスカレーション | 問題に素早く注目を集める | | クローズ時の根本原因の設定 | 他のコントリビューターとの調整 | @@ -41,15 +41,15 @@ doublezero contributor update \ 1. [https://doublezero.xyz/ops-management](https://doublezero.xyz/ops-management) にアクセスします。 2. **Connect Your Wallet** をクリックし、ウォレットを選択します。 -3. Ops Managerキーの所有権を証明するためにメッセージに署名します。 +3. メッセージに署名して、Ops Managerキーの所有権を証明します。 認証が完了すると、**Incident Tracking Table** が表示されます。 -アカウント設定は **Settings** メニュー（右上の歯車アイコン）にあります：API Key Management、User Management、Escalation Contacts。表示されるオプションはロールによって異なります。 +アカウント設定は **Settings** メニュー（右上の歯車アイコン）の中にあります：API Key Management、User Management、Escalation Contacts。表示されるオプションはロールによって異なります。 ### 3. APIキーの作成（オプション） -Webフォームの代わりにプログラムでアクセスする場合： +Webフォームの代わりにプログラムからアクセスする場合： 1. **Settings** メニュー（歯車アイコン）を開き、**API Key Management** を選択します。 2. 1つ以上のAPIキーを作成します。 @@ -61,54 +61,54 @@ Webフォームの代わりにプログラムでアクセスする場合： インシデントとは、計画外のサービスに影響を与えるイベントです。 -### 重大度レベル +### 重要度レベル -DoubleZeroネットワークへの影響に基づいて重大度を割り当てます。状況の変化に応じて重大度を更新できます。 +DoubleZeroネットワークへの影響に基づいて重要度を割り当てます。状況の進展に応じて重要度を更新できます。 -| 重大度 | 影響 | 対応 | +| 重要度 | 影響 | 対応 | |----------|--------|----------| -| `sev1` | フォールバックなしの完全な障害、または重大なコントロール/データプレーンの障害 | 勤務時間外であっても、直ちにすべてを中断して対応。DoubleZero Foundationに即座にエスカレーション。 | -| `sev2` | 部分的だが大きな影響；フォールバックの可能性があるサービス劣化 | 緊急として対応。積極的に調整。持続的な劣化に対しては夜間対応も必要。 | -| `sev3` | ユーザーへの影響が限定的またはなし；未解決の場合はエスカレーションの可能性あり | 勤務時間中の最優先事項。注意深く監視。影響が増大しない限り、時間外のエスカレーションは不要。 | +| `sev1` | 全面的な停止、またはフォールバックのない主要なコントロール/データプレーンの障害 | 営業時間外であっても直ちにすべてを中断して対応。DoubleZero Foundationに即座にエスカレーション。 | +| `sev2` | 部分的だが大きな影響；フォールバックの可能性があるサービス劣化 | 緊急として扱う。積極的に調整。持続的な劣化に対しては夜間対応が必要。 | +| `sev3` | 限定的またはユーザーに見える影響なし；未解決の場合エスカレートの可能性 | 営業時間中の最優先事項。綿密に監視。影響が拡大しない限り、時間外のエスカレーションは不要。 | -??? note "重大度の例" +??? note "重要度の例" **Sev1の例** - - DoubleZero上のユーザートラフィックの10%以上がブラックホール化、公衆インターネットへのフォールバックなし + - DoubleZero上でユーザートラフィックの10%以上がブラックホール化し、パブリックインターネットへのフォールバックなし - ユーザーのオンボーディング、接続、または切断の試行の80%以上が失敗 - DZDの20%以上がインターフェースエラーを報告 - コントローラーがDZDエージェントに有効だが不正な設定を返している **Sev2の例** - - ユーザーの20%以上がDoubleZeroトンネル経由でトラフィックを送受信できないが、公衆インターネットにフォールバック中 - - DoubleZero上のユーザートラフィックの0〜10%がフォールバックなしでブラックホール化 + - ユーザーの20%以上がDoubleZeroトンネル経由でトラフィックを送受信できないが、パブリックインターネットにフォールバック可能 + - フォールバックなしでDoubleZero上のユーザートラフィックの0〜10%がブラックホール化 - 新規ユーザーのオンボーディング、接続、または切断の試行の20〜80%が失敗 - 設定エージェントの20%以上がDZD設定の適用に失敗 - DZDの0〜20%がインターフェースエラーを報告 - 上流の問題によるオブザーバビリティの喪失（監視/アラートがダウン） - オンチェーンデータパイプラインがダウンまたは不正なデータを生成 - インターネットレイテンシの収集または送信の20%以上が失敗 - - DZDエージェントがコントローラーにアクセスできない - - コントローラーがDZDに対して適用されない無効な設定を返している + - DZDエージェントからコントローラーにアクセス不能 + - コントローラーがDZDに適用されない無効な設定を返している **Sev3の例** - - ユーザーの0〜20%がDoubleZeroトンネル経由でトラフィックを送受信できないが、公衆インターネットにフォールバック可能 + - ユーザーの0〜20%がDoubleZeroトンネル経由でトラフィックを送受信できないが、パブリックインターネットへのフォールバックあり - DZDの0〜20%がインターフェースエラーを報告 - DZDの0〜20%が設定エージェントの障害を経験 - ユーザーのオンボーディング、接続、または切断の試行の0〜20%が失敗 - - 単一のデータプロバイダーにおけるインターネットレイテンシの収集または送信の20%以上が失敗 - - すべてのデータプロバイダーにおけるインターネットレイテンシの収集または送信の0〜20%が失敗 + - 単一データプロバイダーのインターネットレイテンシ収集または送信の20%以上が失敗 + - 全データプロバイダーのインターネットレイテンシ収集または送信の0〜20%が失敗 - サイレンスにできないアラートノイズを引き起こすバグまたは技術的負債 - - デバイスの0〜20%でDIAがダウンまたはレジャーRPCネットワーキングの問題が数時間発生 - - 軽微なバグ、外観上のエラー、顧客トラフィックに影響しない孤立したインシデントなどの低影響の問題 + - デバイスの0〜20%で数時間にわたるDIAダウンまたはレジャーRPCネットワーキングの問題 + - 顧客トラフィックに影響しない軽微なバグ、表示上のエラー、または個別のインシデントなどの低影響の問題 - サービス中断なしにごく一部のデバイスが断続的にエラーを報告 -### インシデントのオープン +### インシデントの作成 -ポータルで **Create New Record** をクリックし、Type = **Incident** を選択するか、API経由で送信します。 +**Create New Record** をクリックし、ポータルでType = **Incident** を選択するか、API経由で送信します。 **必須：** @@ -117,70 +117,70 @@ DoubleZeroネットワークへの影響に基づいて重大度を割り当て | `title` | 短い概要（最大100文字） | | `description` | 詳細な説明（最大500文字） | | `severity` | `sev1`、`sev2`、または `sev3` | -| `status` | 作成時に終了ステータス（`resolved`、`closed`）には設定できません | -| デバイスおよび/またはリンク | 少なくとも1つ必要。Webフォームでは、デバイスコードとリンクコードのドロップダウンから選択します。API使用時は、対応するpubkeyを `device_pubkey` および/または `affected_link_pubkey` として渡します。 | +| `status` | 作成時に終了状態（`resolved`、`closed`）には設定できません | +| デバイスおよび/またはリンク | 少なくとも1つ必要。Webフォームでは、デバイスコードとリンクコードのドロップダウンから選択します。APIを使用する場合は、対応するpubkeyを `device_pubkey` および/または `affected_link_pubkey` として渡します。 | **オプション：** | フィールド | 説明 | |-------|-------------| -| `reporter_name` / `reporter_email` | 連絡先情報 | +| `reporter_name` / `reporter_email` | あなたの連絡先情報 | | `assignee` | 解決の責任者 | -| `internal_reference` | 内部チケットID（例：Jira、ServiceNow） | +| `internal_reference` | 社内チケットID（例：Jira、ServiceNow） | | `start_at` | デフォルトは作成時刻；編集可能 | -作成されると、チケットID、重大度、影響を受けるデバイス/リンク、コントリビューター名を含む通知がコントリビューターインシデントSlackチャンネルに投稿されます。 +作成されると、チケットID、重要度、影響を受けるデバイス/リンク、およびコントリビューター名とともに、コントリビューターインシデントSlackチャンネルに通知が投稿されます。 ### インシデントの更新 -インシデントの進行に伴い、チケットのステータスを最新の状態に保ってください。これは、他のコントリビューターとDZが何が対応中であるかを理解するためのシグナルです。 +インシデントの進行に合わせて、チケットのステータスを最新に保ってください。これは、他のコントリビューターやDZが何が対応中かを把握するための指標です。 | ステータス | 設定するタイミング | |--------|----------------| -| `open` | 初期状態：問題が報告されたが、まだ対応されていない | -| `acknowledged` | 確認し、対応を引き受けた | +| `open` | 初期状態：問題が報告され、まだ対応されていない | +| `acknowledged` | 確認し、オーナーシップを取った | | `investigating` | 積極的に診断中：ログの収集、メトリクスの確認 | -| `mitigating` | 根本原因が判明または推測された；修正またはワークアラウンドを適用中 | -| `monitoring` | 修正を適用済み；それが持続するか監視中 | -| `resolved` | 問題の修正を確認済み；**根本原因が必須** | -| `closed` | 完全に完了；追加のアクション不要；**根本原因が必須** | +| `mitigating` | 根本原因が判明または推定；修正またはワークアラウンドを適用中 | +| `monitoring` | 修正を適用済み；持続するか確認のため監視中 | +| `resolved` | 問題の修正を確認；**根本原因が必須** | +| `closed` | 完全に完了；追加アクション不要；**根本原因が必須** | ``` open → acknowledged → investigating → mitigating → monitoring → resolved → closed ``` -適切であればステータスをスキップできます。例えば、すぐに作業を開始した場合は `open` から直接 `investigating` に移行できます。現在の状態に最も正確なステータスを常に使用してください。 +適切であればステータスを飛ばすことができます。例えば、すぐに対応を開始した場合は `open` から直接 `investigating` にジャンプできます。常に現在の状態に最も正確なステータスを使用してください。 -各ステータス更新は、元のSlack通知スレッドにリプライとして投稿されます。 +各ステータス更新は、元のSlack通知スレッドに返信として投稿されます。 ### インシデントのクローズ -インシデントを `resolved` または `closed` に移行するには、**根本原因**を設定する必要があります。根本原因がすでに判明している場合は、それ以前のステージで設定できます。クローズ時には必須となります。 +インシデントを `resolved` または `closed` に移行するには、**根本原因** を設定する必要があります。既に判明している場合は、より前の段階で根本原因を設定できます。クローズ時には必須となります。 | コード | 説明 | |------|-------------| | `hardware` | ハードウェアの修理、交換、またはアップグレード（SFP、NIC、ケーブル、デバイス） | | `software` | ソフトウェアまたはファームウェアの修正、更新、または再起動 | | `configuration` | 設定の変更、修正、またはロールバック | -| `capacity` | 輻輳、容量制限、またはトラフィック管理 | +| `capacity` | 輻輳、キャパシティ制限、またはトラフィック管理 | | `carrier` | 回線、波長、またはクロスコネクトプロバイダーの問題 | -| `network_external` | コントリビューターの管理外にある外部ネットワークの問題 | +| `network_external` | コントリビューターの管理外の外部ネットワーク問題 | | `facility` | データセンターインフラの問題（電源、冷却） | -| `fiber_cut` | 物理的な光ファイバー損傷の修復 | +| `fiber_cut` | 物理的なファイバー損傷の修復 | | `security` | セキュリティインシデントの緩和 | | `human_error` | 運用上のミスの修正 | -| `false_positive` | 調査後に実際の問題は見つからなかった | -| `duplicate` | 別のチケットで既に追跡されている | -| `self_resolved` | 介入なしに問題が解決した | -| `dz_managed` | DoubleZeroが管理するソフトウェアコンポーネント（activator、controllerなど）の問題 | +| `false_positive` | 調査後に実際の問題が見つからなかった | +| `duplicate` | 別のチケットで既に追跡中 | +| `self_resolved` | 介入なしに問題が解決 | +| `dz_managed` | DoubleZero管理のソフトウェアコンポーネント（activator、controllerなど）の問題 | --- ## メンテナンス -メンテナンスレコードは、可用性に影響を与える可能性のある計画的で期間が定められた作業です。他のコントリビューターが確認し、競合するウィンドウを回避できるように、事前に作成してください。 +メンテナンスレコードは、可用性に影響する可能性のある計画的な時間制限のある作業です。他のコントリビューターがウィンドウの競合を確認・回避できるよう、事前に作成してください。 -### メンテナンスのスケジューリング +### メンテナンスのスケジュール ポータルで **Create New Record** > **Maintenance** をクリックするか、API経由で送信します。 @@ -190,23 +190,26 @@ open → acknowledged → investigating → mitigating → monitoring → resolv |-------|-------------| | `title` | 短い概要（最大100文字） | | `description` | 詳細な説明（最大500文字） | +| `severity` | `sev1`、`sev2`、または `sev3`。予想されるユーザー影響に基づいて設定します（以下の注記を参照）。 | | `start_at` | 計画開始時刻（UTC） | -| `end_at` | 計画終了時刻（UTC）；`start_at` より後でなければならない | -| デバイスおよび/またはリンク | 少なくとも1つ必要。Webフォームでは、デバイスコードとリンクコードのドロップダウンから選択します。API使用時は、対応するpubkeyを `device_pubkey` および/または `affected_link_pubkey` として渡します。 | +| `end_at` | 計画終了時刻（UTC）；`start_at` より後である必要があります | +| デバイスおよび/またはリンク | 少なくとも1つ必要。Webフォームでは、デバイスコードとリンクコードのドロップダウンから選択します。APIを使用する場合は、対応するpubkeyを `device_pubkey` および/または `affected_link_pubkey` として渡します。 | -作成されると、チケットID、影響を受けるデバイス/リンク、計画ウィンドウ、コントリビューター名を含む通知がコントリビューターメンテナンスSlackチャンネルに投稿されます。 +重要度はインシデントと同じ方法でメンテナンスにも適用されます。ウィンドウ中に予想されるユーザー影響に基づいて、[上記の重要度レベル](#重要度レベル)を使用して設定してください。 + +作成されると、チケットID、影響を受けるデバイス/リンク、計画ウィンドウ、およびコントリビューター名とともに、コントリビューターメンテナンスSlackチャンネルに通知が投稿されます。 ### メンテナンスステータスの管理 -ウィンドウの進行に伴い、ステータスを最新の状態に保ってください。 +ウィンドウの進行に合わせてステータスを最新に保ってください。 | ステータス | 設定するタイミング | |--------|----------------| -| `planned` | スケジュール済み、まだ開始していない | +| `planned` | スケジュール済み、まだ開始されていない | | `in-progress` | 作業が開始された | -| `completed` | 作業が正常に完了した | +| `completed` | 作業が正常に完了 | | `closed` | `end_at` の24時間後に自動設定 | -| `cancelled` | 実行前または実行中にキャンセルされた | +| `cancelled` | 実行前または実行中にキャンセル | ``` planned → in-progress → completed → closed (end_atの24時間後に自動) @@ -218,67 +221,67 @@ planned → in-progress → completed → closed (end_atの24時間後に自動) ## エスカレーション連絡先 -エスカレーション連絡先は、ネットワークのあなたの担当部分に問題が発生した際に、DoubleZeroや他のコントリビューターが誰に連絡すればよいかを示します。自分の組織の連絡先は自分で設定します。連絡先は個人でもチーム（NOCなど）でもかまいません。各連絡先には1つ以上の連絡方法と、オンコールのスケジュールがあります。 +エスカレーション連絡先は、ネットワークのあなたの担当部分に問題が発生した場合に、DoubleZeroや他のコントリビューターが誰に連絡すべきかを示します。自組織の連絡先は自分で設定します。連絡先は個人またはNOCなどのチームにすることができます。各連絡先には、1つ以上の連絡方法とオンコールのスケジュールがあります。 -**Settings** メニュー（歯車アイコン）を開き、**Escalation Contacts** を選択します。連絡先の追加や編集ができるのはops managerのみです。 +**Settings** メニュー（歯車アイコン）を開き、**Escalation Contacts** を選択します。連絡先の追加・編集はops managerのみが行えます。 ### 連絡先の追加 -各連絡先に対して、以下を設定します： +各連絡先に以下を設定します： | フィールド | 説明 | |-------|-------------| -| Name | 連絡先の名前。個人でもNOCなどのチームでも可 | -| Timezone | ローカルタイムゾーン。スケジュールの読み取りに使用 | -| Availability | **24/7**、または連絡先がオンコールである1つ以上の週次タイムスロット | -| Contact methods | 連絡先に到達するための1つ以上の方法。優先順位順 | +| Name | 連絡先の名前（個人またはNOCなどのチーム） | +| Timezone | ローカルタイムゾーン（スケジュールの読み取りに使用） | +| Availability | **24/7**、または連絡先がオンコールである1つ以上の週間タイムスロット | +| Contact methods | 優先順位順の1つ以上の連絡方法 | -サポートされている連絡方法は、メール、電話、Slack、Telegram、WhatsAppです。順序は重要です：最初の方法が最初に試されます。 +サポートされている連絡方法は、メール、電話、Slack、Telegram、WhatsAppです。順序が重要です：最初の方法が最初に試すべき方法です。 ### 可用性とカバレッジギャップ -連絡先は、24時間365日（24/7）利用可能であるか、定義した週次タイムスロット（例：月曜日〜金曜日、09:00〜17:00）の間に利用可能です。スロットは連絡先のローカルタイムゾーンで入力され、UTCで表示されるため、夏時間は自動的に処理されます。 +連絡先は24時間年中無休（24/7）で対応可能か、定義した週間タイムスロット中に対応可能です（例：月曜日から金曜日、09:00〜17:00）。スロットは連絡先のローカルタイムゾーンで入力され、UTCで表示されるため、夏時間は自動的に処理されます。 -**カバレッジギャップ**ビューには、組織から誰もオンコールでない毎週の時間帯が表示されます。ギャップを見つけて埋めるために使用してください。 +**カバレッジギャップ** ビューは、組織内の誰もオンコールでない各週の時間帯を表示します。ギャップを見つけて解消するために活用してください。 ### ローテーションウィンドウ -1週間は30分のウィンドウに分割されます。各ウィンドウに対して、連絡先に到達する順序を設定できます。これにより、各連絡先を編集することなくオンコールローテーションを実行できます。 +1週間は30分単位のウィンドウに分割されます。各ウィンドウに対して、連絡先に連絡する順序を設定できます。これにより、各連絡先を編集せずにオンコールローテーションを運用できます。 -### 表示設定 +### 可視性 -連絡先を誰が見られるかを制御できます。DoubleZeroは常に見ることができます。他に誰が見られるかを選択します： +連絡先を誰が見られるかを制御できます。DoubleZeroは常に見ることができます。他に誰が見られるかはあなたが選択します： -| 設定 | 連絡先を見られる他の対象 | +| 設定 | 連絡先を見られるその他の人 | |---------|-------------------------------| | DoubleZeroのみ（デフォルト） | 他のコントリビューターなし | | 全員 | すべてのコントリビューター | | 一部のコントリビューター | 選択したコントリビューターのみ | -自分のチームは常に連絡先を見ることができます。表示設定は組織全体に対して一度設定され、すべての連絡先に適用されます。 +自分のチームは常に連絡先を見ることができます。可視性は組織全体に対して一度設定され、すべての連絡先に適用されます。 --- ## ユーザー管理 -デフォルトでは、Ops Managerキーが組織を代表して操作できる唯一のアカウントです。チームメンバーを追加して、複数の人がチケットを管理できるようにできます。 +デフォルトでは、Ops Managerキーのみが組織のために操作できるアカウントです。チームメンバーを追加して、複数の人がチケットを管理できるようにすることができます。 -**Settings** メニュー（歯車アイコン）を開き、**User Management** を選択します。チームメンバーの追加や削除ができるのはops managerのみです。 +**Settings** メニュー（歯車アイコン）を開き、**User Management** を選択します。チームメンバーの追加・削除はops managerのみが行えます。 -各チームメンバーに対して、以下を設定します： +各チームメンバーに以下を設定します： | フィールド | 説明 | |-------|-------------| -| Name | メンバーの名前 | +| Name | そのメンバーの名前 | | Wallet pubkey | サインインに使用するSolanaウォレット | | Access level | **Read** または **Read-write** | アクセスレベル： -- **Read**：チケットとエスカレーション連絡先の閲覧、および読み取り専用APIキーの作成が可能。チケットの作成、更新、クローズはできません。 -- **Read-write**：チケットの作成、更新、クローズへのフルアクセス、および任意のレベルのAPIキーの作成が可能。 +- **Read**：チケットとエスカレーション連絡先の閲覧、読み取り専用APIキーの作成が可能。チケットの作成、更新、クローズはできません。 +- **Read-write**：チケットの作成、更新、クローズへの完全アクセス、任意のレベルのAPIキーの作成が可能。 -各チームメンバーは、Ops Managerキーを接続したのと同じ方法で、自分のウォレットでサインインします。 +各チームメンバーは、Ops Managerキーの接続と同じ方法で、自分のウォレットでサインインします。 --- @@ -286,28 +289,28 @@ planned → in-progress → completed → closed (end_atの24時間後に自動) ### コントリビューターができること -- 自分のデバイスとリンクに対してのみチケットを作成・管理できる。 -- 自分自身にチケットを割り当てるか、DZ/Malbeclabsにエスカレーションできる。 -- すべてのコントリビューターのすべてのチケットを閲覧できる。 -- チームメンバーを追加し、アクセスレベルを設定できる（ops managerのみ）。 -- 自分の組織のエスカレーション連絡先を管理できる（ops managerのみ）。 +- 自分のデバイスとリンクに対してのみチケットを作成・管理。 +- チケットを自分に割り当てるか、DZ/Malbeclabsにエスカレーション。 +- すべてのコントリビューターのすべてのチケットを閲覧。 +- チームメンバーの追加とアクセスレベルの設定（ops managerのみ）。 +- 自組織のエスカレーション連絡先の管理（ops managerのみ）。 ### DZ/Malbeclabs管理者ができること -- 任意のコントリビューターのデバイスとリンクに対してチケットを作成できる。 -- コントリビューター間でチケットを割り当てまたは再割り当てできる。 -- エスカレーションとサポートリクエストを処理できる。 +- 任意のコントリビューターのデバイスとリンクに対してチケットを作成。 +- コントリビューター間でチケットを割り当てまたは再割り当て。 +- エスカレーションとサポートリクエストの処理。 ### DZXリンクの所有権 -DZXリンクは、2つの異なるコントリビューターのデバイスを接続します。**A側**のコントリビューター（リンク名の最初のデバイス）がリンクを所有し、そのリンクに対してチケットを作成できる唯一のコントリビューターです。 +DZXリンクは、2つの異なるコントリビューターのデバイスを接続します。**A側** コントリビューター（リンク名の最初のデバイス）がリンクを所有し、そのリンクに対してチケットを作成できる唯一の存在です。 **例：** リンク `deviceA:deviceB` の場合、`deviceA` を所有するコントリビューターがリンクを所有します。 -**問題がZ側にある場合：** +**Z側に問題がある場合：** -1. A側のコントリビューターがDZXリンクのチケットを作成します。 +1. A側コントリビューターがDZXリンクのチケットを作成します。 2. チケットをDZ/Malbeclabsに割り当てます。 -3. DZ/Malbeclabsが調査し、必要に応じてZ側のコントリビューターに再割り当てします。 +3. DZ/Malbeclabsが調査し、必要に応じてZ側コントリビューターに再割り当てします。 -このワークフローには制限があることを認識しています。現在、Z側のコントリビューターは自分が所有していないDZXリンクのチケットを作成できないため、調整はDZ/Malbeclabsを経由する必要があります。DZXリンクの両側がインシデントとメンテナンスを独立して申告できるように、改善に取り組んでいます。 \ No newline at end of file +このワークフローに制限があることは認識しています。現在、Z側コントリビューターは自分が所有していないDZXリンクのチケットを作成できないため、調整はDZ/Malbeclabsを経由する必要があります。DZXリンクの両側が独立してインシデントとメンテナンスを報告できるよう、改善に取り組んでいます。 \ No newline at end of file diff --git a/docs/contribute-ops-management.ko.md b/docs/contribute-ops-management.ko.md index 3827bc0..35d9671 100644 --- a/docs/contribute-ops-management.ko.md +++ b/docs/contribute-ops-management.ko.md @@ -6,17 +6,17 @@ DoubleZero OPS 관리 포털은 기여자들이 네트워크 전반에 걸쳐 ## 포털 vs Slack -OPS 관리 포털과 Slack은 함께 작동합니다. 모든 인시던트와 유지보수는 티켓으로 추적되며, 포털 또는 API를 통해 접근할 수 있습니다. 각 티켓은 적절한 Slack 채널에 자동으로 알림을 보내고, 모든 기여자에게 네트워크에서 일어나고 있는 일에 대한 공유 뷰를 제공합니다. Slack은 대화가 이루어지는 곳입니다: 로그 공유, 다른 기여자와의 조율, 활성 이슈에 대한 협업 등. +OPS 관리 포털과 Slack은 함께 작동합니다. 모든 인시던트와 유지보수는 티켓으로 추적되며, 포털이나 API를 통해 접근할 수 있습니다. 각 티켓은 적절한 Slack 채널에 자동으로 알림을 보내고, 모든 기여자에게 네트워크에서 발생하고 있는 상황에 대한 공유 뷰를 제공합니다. Slack은 대화가 이루어지는 곳으로, 로그 공유, 다른 기여자와의 조율, 그리고 활성 이슈에 대한 협업이 이루어집니다. -티켓은 포털이든 API를 통해서든 생성된 정식 기록입니다. Slack 스레드는 그렇지 않습니다: 티켓 상태를 업데이트하지 않으며 영구적으로 저장되지 않습니다. 대화가 Slack에서 이루어지고 있더라도 항상 티켓 상태를 최신으로 유지하세요. +티켓은 포털이나 API를 통해 생성되든 공식 기록입니다. Slack 스레드는 그렇지 않습니다: 스레드는 티켓 상태를 업데이트하지 않으며 영구적으로 저장되지 않습니다. 대화가 Slack에서 이루어지더라도 항상 티켓 상태를 최신으로 유지하세요. -포털과 Slack은 서로 다른 용도를 가집니다. 둘 다 사용하되, 올바른 용도에 맞게 사용하세요. +포털과 Slack은 서로 다른 목적을 가지고 있습니다. 둘 다 사용하되, 적절한 용도에 맞게 사용하세요. -| 포털(또는 API) 사용 용도... | Slack 사용 용도... | +| 포털(또는 API) 사용 목적... | Slack 사용 목적... | |-------------------------------|-----------------| -| 티켓 열기, 업데이트, 닫기 | 활성 이슈에 대한 대화 및 협업 | +| 티켓 생성, 업데이트 및 종료 | 활성 이슈에 대한 대화와 협업 | | 상태 전환 기록 | 로그, 스크린샷 공유 또는 통화 시작 | -| 티켓 할당 또는 에스컬레이션 | 문제에 대한 빠른 관심 확보 | +| 티켓 할당 또는 에스컬레이션 | 문제에 대해 빠르게 주목받기 | | 종료 시 근본 원인 설정 | 다른 기여자와의 조율 | @@ -25,7 +25,7 @@ OPS 관리 포털과 Slack은 함께 작동합니다. 모든 인시던트와 유 ## 온보딩 -포털을 사용하기 전에 이 단계를 한 번 완료하세요. +포털을 사용하기 전에 다음 단계를 한 번 완료하세요. ### 1. Ops Manager 키 설정 @@ -39,7 +39,7 @@ doublezero contributor update \ ### 2. 포털에서 지갑 연결 -1. [https://doublezero.xyz/ops-management](https://doublezero.xyz/ops-management)로 이동합니다. +1. [https://doublezero.xyz/ops-management](https://doublezero.xyz/ops-management)으로 이동합니다. 2. **Connect Your Wallet**을 클릭하고 지갑을 선택합니다. 3. Ops Manager 키의 소유권을 증명하기 위해 메시지에 서명합니다. @@ -49,7 +49,7 @@ doublezero contributor update \ ### 3. API 키 생성 (선택 사항) -웹 양식 대신 프로그래밍 방식으로 접근하려면: +웹 폼 대신 프로그래밍 방식으로 접근하려면: 1. **Settings** 메뉴(톱니바퀴 아이콘)를 열고 **API Key Management**를 선택합니다. 2. 하나 이상의 API 키를 생성합니다. @@ -67,149 +67,152 @@ DoubleZero 네트워크에 대한 영향을 기반으로 심각도를 지정합 | 심각도 | 영향 | 대응 | |----------|--------|----------| -| `sev1` | 대체 수단이 없는 전면 장애 또는 주요 제어/데이터 플레인 고장 | 근무 시간 외라도 즉시 모든 것을 중단하고 대응합니다. DoubleZero Foundation에 즉시 에스컬레이션합니다. | -| `sev2` | 부분적이지만 상당한 영향; 대체 가능성이 있는 서비스 저하 | 긴급으로 처리합니다. 적극적으로 조율합니다. 지속적인 저하에 대해 야간 대응이 필요합니다. | -| `sev3` | 제한적이거나 사용자가 인지할 수 없는 영향; 해결되지 않으면 에스컬레이션될 가능성 | 근무 시간 내 최우선 순위입니다. 면밀히 모니터링합니다. 영향이 증가하지 않는 한 근무 시간 외 에스컬레이션은 불필요합니다. | +| `sev1` | 전면 장애 또는 대체 수단이 없는 주요 제어/데이터 플레인 파손 | 근무 시간 외에도 즉시 모든 것을 중단하고 대응. DoubleZero Foundation에 즉시 에스컬레이션. | +| `sev2` | 부분적이지만 상당한 영향; 대체 수단이 가능한 서비스 저하 | 긴급 처리. 적극적으로 조율. 지속적인 저하에 대해 야간 대응 필요. | +| `sev3` | 제한적이거나 사용자에게 보이지 않는 영향; 해결되지 않으면 에스컬레이션 가능 | 근무 시간 중 최우선 순위. 면밀히 모니터링. 영향이 증가하지 않는 한 근무 시간 외 에스컬레이션 불필요. | ??? note "심각도 예시" **Sev1 예시** - - DoubleZero에서 사용자 트래픽의 10% 이상이 블랙홀링되고 공용 인터넷으로의 대체 불가 + - DoubleZero에서 사용자 트래픽의 10% 이상이 블랙홀 처리되고 공용 인터넷으로의 대체 수단 없음 - 사용자 온보딩, 연결 또는 연결 해제 시도의 80% 이상 실패 - DZD의 20% 이상이 인터페이스 오류 보고 - - 컨트롤러가 DZD 에이전트에 유효하지만 잘못된 설정을 반환 + - 컨트롤러가 DZD 에이전트에 유효하지만 잘못된 설정 반환 **Sev2 예시** - - 사용자의 20% 이상이 DoubleZero 터널을 통해 트래픽을 송수신할 수 없지만, 공용 인터넷으로 폴백 가능 - - 대체 없이 DoubleZero에서 사용자 트래픽의 0–10%가 블랙홀링 + - 사용자의 20% 이상이 DoubleZero 터널을 통해 트래픽을 송수신할 수 없지만 공용 인터넷으로 폴백 + - 대체 수단 없이 DoubleZero에서 사용자 트래픽의 0–10%가 블랙홀 처리 - 신규 사용자 온보딩, 연결 또는 연결 해제 시도의 20–80% 실패 - 설정 에이전트의 20% 이상이 DZD 설정 적용 실패 - DZD의 0–20%가 인터페이스 오류 보고 - - 업스트림 문제로 인한 관찰성 손실 (모니터링/알림 다운) + - 관측성 손실을 유발하는 업스트림 이슈 (모니터링/알림 다운) - 온체인 데이터 파이프라인 다운 또는 잘못된 데이터 생성 - - 인터넷 지연 수집 또는 제출의 20% 이상 실패 + - 인터넷 지연 시간 수집 또는 제출의 20% 이상 실패 - DZD 에이전트가 컨트롤러에 접근 불가 - - 컨트롤러가 DZD에 적용되지 않을 잘못된 설정을 반환 + - 컨트롤러가 DZD에 적용되지 않을 잘못된 설정 반환 **Sev3 예시** - - 사용자의 0–20%가 DoubleZero 터널을 통해 트래픽을 송수신할 수 없지만, 공용 인터넷으로 폴백 가능 + - 사용자의 0–20%가 DoubleZero 터널을 통해 트래픽을 송수신할 수 없지만 공용 인터넷으로 폴백 - DZD의 0–20%가 인터페이스 오류 보고 - DZD의 0–20%가 설정 에이전트 실패 경험 - 사용자 온보딩, 연결 또는 연결 해제 시도의 0–20% 실패 - - 단일 데이터 제공업체의 인터넷 지연 수집 또는 제출의 20% 이상 실패 - - 모든 데이터 제공업체의 인터넷 지연 수집 또는 제출의 0–20% 실패 - - 음소거할 수 없는 알림 노이즈를 유발하는 버그 또는 기술 부채 - - 수 시간 동안 장치의 0–20%에 대해 DIA 다운 또는 레저 RPC 네트워킹 문제 - - 사소한 버그, 외관 오류 또는 고객 트래픽에 영향을 미치지 않는 격리된 인시던트와 같은 낮은 영향의 이슈 - - 서비스 중단 없이 간헐적으로 오류를 보고하는 소수의 장치 + - 단일 데이터 제공자에 대해 인터넷 지연 시간 수집 또는 제출의 20% 이상 실패 + - 모든 데이터 제공자에 대해 인터넷 지연 시간 수집 또는 제출의 0–20% 실패 + - 무음 처리할 수 없는 알림 노이즈를 유발하는 버그 또는 기술 부채 + - 수 시간 동안 디바이스의 0–20%에 대해 DIA 다운 또는 원장 RPC 네트워킹 이슈 + - 사소한 버그, 외관 오류 또는 고객 트래픽에 영향을 미치지 않는 격리된 인시던트 등 영향이 낮은 이슈 + - 소수의 디바이스가 서비스 중단 없이 간헐적으로 오류 보고 -### 인시던트 열기 +### 인시던트 생성 -**Create New Record**를 클릭하고, 포털에서 Type = **Incident**를 선택하거나 API를 통해 제출합니다. +**Create New Record**를 클릭하고 포털에서 Type = **Incident**를 선택하거나, API를 통해 제출합니다. **필수:** | 필드 | 설명 | |-------|-------------| | `title` | 짧은 요약 (최대 100자) | -| `description` | 상세한 설명 (최대 500자) | -| `severity` | `sev1`, `sev2`, 또는 `sev3` | +| `description` | 상세 설명 (최대 500자) | +| `severity` | `sev1`, `sev2` 또는 `sev3` | | `status` | 생성 시 종료 상태(`resolved`, `closed`)로 설정할 수 없음 | -| Device 및/또는 Link | 최소 하나 필수. 웹 양식에서는 드롭다운에서 장치 및 링크 코드를 선택합니다. API를 사용할 때는 해당하는 공개키를 `device_pubkey` 및/또는 `affected_link_pubkey`로 전달합니다. | +| Device 및/또는 Link | 최소 하나 필수. 웹 폼에서는 드롭다운에서 디바이스 및 링크 코드를 선택합니다. API 사용 시에는 해당 공개키를 `device_pubkey` 및/또는 `affected_link_pubkey`로 전달합니다. | **선택 사항:** | 필드 | 설명 | |-------|-------------| | `reporter_name` / `reporter_email` | 연락처 정보 | -| `assignee` | 해결 책임자 | +| `assignee` | 해결 담당자 | | `internal_reference` | 내부 티켓 ID (예: Jira, ServiceNow) | | `start_at` | 기본값은 생성 시간; 편집 가능 | -생성되면 티켓 ID, 심각도, 영향받는 장치/링크, 기여자 이름과 함께 기여자 인시던트 Slack 채널에 알림이 게시됩니다. +생성되면 티켓 ID, 심각도, 영향받는 디바이스/링크, 기여자 이름이 포함된 알림이 기여자 인시던트 Slack 채널에 게시됩니다. ### 인시던트 업데이트 -인시던트가 진행됨에 따라 티켓 상태를 최신으로 유지하세요. 이것은 다른 기여자와 DZ가 무엇이 작업 중인지 이해하기 위해 사용하는 신호입니다. +인시던트가 진행됨에 따라 티켓 상태를 최신으로 유지하세요. 이것이 다른 기여자와 DZ가 무엇이 작업 중인지 이해하기 위해 참조하는 신호입니다. | 상태 | 설정 시점 | |--------|----------------| -| `open` | 초기 상태: 이슈가 보고됨, 아직 작업 시작 전 | -| `acknowledged` | 확인했으며 소유권을 가짐 | +| `open` | 초기 상태: 이슈가 보고되었으나 아직 작업 시작 전 | +| `acknowledged` | 확인하고 담당을 맡음 | | `investigating` | 적극적으로 진단 중: 로그 수집, 메트릭 확인 | -| `mitigating` | 근본 원인이 파악되었거나 추정됨; 수정 또는 우회 방법 적용 중 | -| `monitoring` | 수정 적용됨; 유지되는지 확인하기 위해 관찰 중 | +| `mitigating` | 근본 원인이 확인되었거나 의심됨; 수정 또는 우회 방법 적용 중 | +| `monitoring` | 수정 적용됨; 유지되는지 확인 중 | | `resolved` | 이슈 수정 확인됨; **근본 원인 필수** | -| `closed` | 완전히 완료됨; 추가 조치 불필요; **근본 원인 필수** | +| `closed` | 완전히 완료; 추가 조치 불필요; **근본 원인 필수** | ``` open → acknowledged → investigating → mitigating → monitoring → resolved → closed ``` -적절한 경우 상태를 건너뛸 수 있습니다. 예를 들어, 즉시 작업을 시작하면 `open`에서 `investigating`으로 바로 이동할 수 있습니다. 항상 현재 상태에 가장 정확한 상태를 사용하세요. +적절한 경우 상태를 건너뛸 수 있습니다. 예를 들어, 즉시 작업을 시작하는 경우 `open`에서 `investigating`로 바로 이동할 수 있습니다. 항상 현재 상태에 가장 정확한 상태를 사용하세요. -각 상태 업데이트는 원래 Slack 알림 스레드에 답변으로 게시됩니다. +각 상태 업데이트는 원래 Slack 알림 스레드에 답글로 게시됩니다. ### 인시던트 종료 -인시던트를 `resolved` 또는 `closed`로 이동하려면 **근본 원인**을 설정해야 합니다. 이미 알고 있다면 이전 단계에서 근본 원인을 설정할 수 있으며, 종료 시 필수가 됩니다. +인시던트를 `resolved` 또는 `closed`로 이동하려면 **근본 원인**이 설정되어야 합니다. 이미 알고 있는 경우 더 이른 단계에서 근본 원인을 설정할 수 있습니다; 종료 시에는 필수가 됩니다. | 코드 | 설명 | |------|-------------| -| `hardware` | 하드웨어 수리, 교체 또는 업그레이드 (SFP, NIC, 케이블, 장치) | +| `hardware` | 하드웨어 수리, 교체 또는 업그레이드 (SFP, NIC, 케이블, 디바이스) | | `software` | 소프트웨어 또는 펌웨어 수정, 업데이트 또는 재시작 | | `configuration` | 설정 변경, 수정 또는 롤백 | -| `capacity` | 혼잡, 용량 제한 또는 트래픽 관리 | -| `carrier` | 회선, 파장 또는 크로스 커넥트 제공업체 문제 | -| `network_external` | 기여자 통제 밖의 외부 네트워크 문제 | -| `facility` | 데이터센터 인프라 문제 (전원, 냉각) | -| `fiber_cut` | 물리적 광섬유 손상 복구 | +| `capacity` | 혼잡, 용량 한계 또는 트래픽 관리 | +| `carrier` | 회선, 파장 또는 교차 연결 제공자 이슈 | +| `network_external` | 기여자 통제 범위 밖의 외부 네트워크 이슈 | +| `facility` | 데이터센터 인프라 이슈 (전력, 냉각) | +| `fiber_cut` | 물리적 광섬유 손상 수리 | | `security` | 보안 인시던트 완화 | | `human_error` | 운영 실수 수정 | -| `false_positive` | 조사 후 실제 문제가 발견되지 않음 | +| `false_positive` | 조사 후 실제 이슈가 발견되지 않음 | | `duplicate` | 다른 티켓에서 이미 추적 중 | -| `self_resolved` | 개입 없이 이슈가 자체 해결됨 | -| `dz_managed` | DoubleZero 관리 소프트웨어 구성요소(activator, controller 등) 관련 문제 | +| `self_resolved` | 개입 없이 이슈 해결 | +| `dz_managed` | DoubleZero 관리 소프트웨어 구성 요소 (activator, controller 등)의 이슈 | --- ## 유지보수 -유지보수 기록은 가용성에 영향을 줄 수 있는 계획된 시간 제한 활동입니다. 다른 기여자들이 확인하고 충돌하는 시간대를 피할 수 있도록 사전에 생성하세요. +유지보수 기록은 가용성에 영향을 줄 수 있는 계획된, 시간이 제한된 활동입니다. 다른 기여자들이 확인하고 충돌하는 작업 시간대를 피할 수 있도록 사전에 생성하세요. ### 유지보수 예약 -포털에서 **Create New Record** > **Maintenance**를 클릭하거나 API를 통해 제출합니다. +포털에서 **Create New Record** > **Maintenance**를 클릭하거나, API를 통해 제출합니다. **필수:** | 필드 | 설명 | |-------|-------------| | `title` | 짧은 요약 (최대 100자) | -| `description` | 상세한 설명 (최대 500자) | +| `description` | 상세 설명 (최대 500자) | +| `severity` | `sev1`, `sev2` 또는 `sev3`. 예상되는 사용자 영향에 맞게 설정합니다 (아래 참고 사항 참조). | | `start_at` | 계획된 시작 시간 (UTC) | | `end_at` | 계획된 종료 시간 (UTC); `start_at` 이후여야 함 | -| Device 및/또는 Link | 최소 하나 필수. 웹 양식에서는 드롭다운에서 장치 및 링크 코드를 선택합니다. API를 사용할 때는 해당하는 공개키를 `device_pubkey` 및/또는 `affected_link_pubkey`로 전달합니다. | +| Device 및/또는 Link | 최소 하나 필수. 웹 폼에서는 드롭다운에서 디바이스 및 링크 코드를 선택합니다. API 사용 시에는 해당 공개키를 `device_pubkey` 및/또는 `affected_link_pubkey`로 전달합니다. | -생성되면 티켓 ID, 영향받는 장치/링크, 계획된 시간대, 기여자 이름과 함께 기여자 유지보수 Slack 채널에 알림이 게시됩니다. +심각도는 인시던트와 동일한 방식으로 유지보수에 적용됩니다. [위의 심각도 수준](#심각도-수준)을 사용하여 작업 시간대 동안 예상되는 사용자 영향에 맞게 설정하세요. + +생성되면 티켓 ID, 영향받는 디바이스/링크, 계획된 작업 시간대, 기여자 이름이 포함된 알림이 기여자 유지보수 Slack 채널에 게시됩니다. ### 유지보수 상태 관리 -시간대가 진행됨에 따라 상태를 최신으로 유지하세요. +작업 시간대가 진행됨에 따라 상태를 최신으로 유지하세요. | 상태 | 설정 시점 | |--------|----------------| -| `planned` | 예약됨, 아직 시작 전 | +| `planned` | 예약됨, 아직 시작되지 않음 | | `in-progress` | 작업 시작됨 | | `completed` | 작업이 성공적으로 완료됨 | -| `closed` | `end_at` 이후 24시간 뒤 자동 설정 | +| `closed` | `end_at` 이후 24시간 후 자동 설정 | | `cancelled` | 실행 전 또는 실행 중 취소됨 | ``` -planned → in-progress → completed → closed (auto 24h after end_at) +planned → in-progress → completed → closed (end_at 이후 24시간 자동) ↓ ↓ └──────────┴──→ cancelled ``` @@ -218,7 +221,7 @@ planned → in-progress → completed → closed (auto 24h after end_at) ## 에스컬레이션 연락처 -에스컬레이션 연락처는 네트워크의 해당 부분에 문제가 있을 때 DoubleZero와 다른 기여자들이 누구에게 연락해야 하는지 알려줍니다. 조직의 연락처를 직접 설정합니다. 연락처는 개인 또는 NOC와 같은 팀일 수 있습니다. 각 연락처에는 하나 이상의 연락 방법과 당직 일정이 있습니다. +에스컬레이션 연락처는 네트워크의 해당 부분에 문제가 있을 때 DoubleZero와 다른 기여자들이 누구에게 연락해야 하는지를 알려줍니다. 조직의 연락처는 직접 설정합니다. 연락처는 개인 또는 NOC와 같은 팀일 수 있습니다. 각 연락처에는 하나 이상의 연락 방법과 대기 중인 시간표가 있습니다. **Settings** 메뉴(톱니바퀴 아이콘)를 열고 **Escalation Contacts**를 선택합니다. ops manager만 연락처를 추가하거나 편집할 수 있습니다. @@ -228,40 +231,40 @@ planned → in-progress → completed → closed (auto 24h after end_at) | 필드 | 설명 | |-------|-------------| -| Name | 연락처 이름, 개인이든 NOC와 같은 팀이든 | -| Timezone | 일정을 읽는 데 사용되는 현지 시간대 | -| Availability | **24/7**, 또는 연락처가 당직인 하나 이상의 주간 시간대 | +| Name | 연락처의 이름, 개인 또는 NOC와 같은 팀 | +| Timezone | 시간표를 확인하는 데 사용되는 현지 시간대 | +| Availability | **24/7** 또는 연락처가 대기 중인 하나 이상의 주간 시간 슬롯 | | Contact methods | 연락처에 연락하는 하나 이상의 방법, 우선순위 순서 | -지원되는 연락 방법은 이메일, 전화, Slack, Telegram, WhatsApp입니다. 순서가 중요합니다: 첫 번째 방법이 먼저 시도해야 할 방법입니다. +지원되는 연락 방법은 이메일, 전화, Slack, Telegram, WhatsApp입니다. 순서가 중요합니다: 첫 번째 방법이 가장 먼저 시도해야 하는 방법입니다. ### 가용성 및 커버리지 공백 -연락처는 24시간(24/7) 가용하거나, 정의한 주간 시간대(예: 월요일~금요일, 09:00~17:00) 동안 가용합니다. 시간대는 연락처의 현지 시간대로 입력되고 UTC로 표시되므로, 일광 절약 시간이 자동으로 처리됩니다. +연락처는 24시간(24/7) 가용하거나, 정의한 주간 시간 슬롯 동안 가용합니다. 예를 들어 월요일부터 금요일, 09:00에서 17:00까지입니다. 슬롯은 연락처의 현지 시간대로 입력되고 UTC로 표시되므로, 일광 절약 시간이 자동으로 처리됩니다. -**커버리지 공백** 뷰는 매주 조직에서 아무도 당직이 아닌 시간을 보여줍니다. 이를 사용하여 공백을 찾고 해소하세요. +**커버리지 공백** 뷰는 조직에서 아무도 대기하지 않는 주간 시간대를 보여줍니다. 이를 사용하여 공백을 찾고 해소하세요. ### 로테이션 윈도우 -한 주는 30분 단위의 윈도우로 나뉩니다. 각 윈도우에 대해 연락처에 연락하는 순서를 설정할 수 있습니다. 이를 통해 각 연락처를 개별적으로 편집하지 않고도 당직 로테이션을 운영할 수 있습니다. +주간은 30분 단위 윈도우로 분할됩니다. 각 윈도우에 대해 연락처에 도달하는 순서를 설정할 수 있습니다. 이를 통해 각 연락처를 편집하지 않고도 온콜 로테이션을 운영할 수 있습니다. -### 가시성 +### 공개 범위 -연락처를 누가 볼 수 있는지 제어합니다. DoubleZero는 항상 볼 수 있습니다. 그 외에 누가 볼 수 있는지 선택합니다: +연락처를 볼 수 있는 사람을 제어합니다. DoubleZero는 항상 볼 수 있습니다. 그 외 누가 볼 수 있는지는 선택합니다: -| 설정 | 연락처를 볼 수 있는 대상 | +| 설정 | 연락처를 볼 수 있는 사람 | |---------|-------------------------------| -| DoubleZero only (기본값) | 다른 기여자 없음 | -| Everybody | 모든 기여자 | -| Some contributors | 선택한 기여자만 | +| DoubleZero만 (기본값) | 다른 기여자 없음 | +| 모든 사람 | 모든 기여자 | +| 일부 기여자 | 선택한 기여자만 | -소속 팀은 항상 연락처를 볼 수 있습니다. 가시성은 조직 전체에 한 번 설정되며 모든 연락처에 적용됩니다. +자신의 팀은 항상 연락처를 볼 수 있습니다. 공개 범위는 조직 전체에 대해 한 번 설정되며 모든 연락처에 적용됩니다. --- ## 사용자 관리 -기본적으로 Ops Manager 키만 조직을 대신하여 활동할 수 있는 유일한 계정입니다. 여러 사람이 티켓을 관리할 수 있도록 팀원을 추가할 수 있습니다. +기본적으로 Ops Manager 키만 조직을 대신하여 활동할 수 있는 유일한 계정입니다. 팀원을 추가하여 여러 사람이 티켓을 관리할 수 있도록 할 수 있습니다. **Settings** 메뉴(톱니바퀴 아이콘)를 열고 **User Management**를 선택합니다. ops manager만 팀원을 추가하거나 제거할 수 있습니다. @@ -269,16 +272,16 @@ planned → in-progress → completed → closed (auto 24h after end_at) | 필드 | 설명 | |-------|-------------| -| Name | 해당 인물의 이름 | -| Wallet pubkey | 로그인 시 사용하는 Solana 지갑 | +| Name | 해당 인원의 이름 | +| Wallet pubkey | 로그인에 사용하는 Solana 지갑 | | Access level | **Read** 또는 **Read-write** | 접근 수준: -- **Read**: 티켓과 에스컬레이션 연락처를 볼 수 있고, 읽기 전용 API 키를 생성할 수 있습니다. 티켓을 생성, 업데이트 또는 종료할 수 없습니다. -- **Read-write**: 티켓 생성, 업데이트, 종료에 대한 전체 접근 권한이 있으며, 모든 수준의 API 키를 생성할 수 있습니다. +- **Read**: 티켓과 에스컬레이션 연락처를 조회하고, 읽기 전용 API 키를 생성할 수 있습니다. 티켓을 생성, 업데이트 또는 종료할 수 없습니다. +- **Read-write**: 티켓 생성, 업데이트 및 종료에 대한 전체 접근 권한을 가지며, 모든 수준의 API 키를 생성할 수 있습니다. -각 팀원은 Ops Manager 키를 연결했던 것과 같은 방식으로 자신의 지갑으로 로그인합니다. +각 팀원은 Ops Manager 키를 연결한 것과 동일한 방식으로 자신의 지갑으로 로그인합니다. --- @@ -286,28 +289,28 @@ planned → in-progress → completed → closed (auto 24h after end_at) ### 기여자가 할 수 있는 것 -- 자신의 장치와 링크에 대해서만 티켓을 생성하고 관리할 수 있습니다. -- 자신에게 티켓을 할당하거나 DZ/Malbeclabs에 에스컬레이션할 수 있습니다. -- 모든 기여자의 모든 티켓을 볼 수 있습니다. -- 팀원을 추가하고 접근 수준을 설정할 수 있습니다 (ops manager만 해당). -- 조직의 에스컬레이션 연락처를 관리할 수 있습니다 (ops manager만 해당). +- 자신의 디바이스와 링크에 대해서만 티켓을 생성하고 관리합니다. +- 자신에게 티켓을 할당하거나 DZ/Malbeclabs로 에스컬레이션합니다. +- 모든 기여자의 모든 티켓을 조회합니다. +- 팀원을 추가하고 접근 수준을 설정합니다 (ops manager만 가능). +- 조직의 에스컬레이션 연락처를 관리합니다 (ops manager만 가능). ### DZ/Malbeclabs 관리자가 할 수 있는 것 -- 모든 기여자의 장치와 링크에 대해 티켓을 생성할 수 있습니다. -- 기여자 간에 티켓을 할당하거나 재할당할 수 있습니다. -- 에스컬레이션과 지원 요청을 처리할 수 있습니다. +- 모든 기여자의 디바이스와 링크에 대해 티켓을 생성합니다. +- 기여자 간 티켓을 할당하거나 재할당합니다. +- 에스컬레이션 및 지원 요청을 처리합니다. ### DZX 링크 소유권 -DZX 링크는 서로 다른 두 기여자의 장치를 연결합니다. **A-side** 기여자(링크 이름의 첫 번째 장치)가 링크를 소유하며, 해당 링크에 대해 티켓을 생성할 수 있는 유일한 주체입니다. +DZX 링크는 두 명의 서로 다른 기여자의 디바이스를 연결합니다. **A-side** 기여자(링크 이름의 첫 번째 디바이스)가 링크를 소유하며, 해당 링크에 대해 티켓을 생성할 수 있는 유일한 사람입니다. -**예시:** `deviceA:deviceB` 링크의 경우, `deviceA`를 소유한 기여자가 링크를 소유합니다. +**예시:** 링크 `deviceA:deviceB`의 경우, `deviceA`를 소유한 기여자가 링크를 소유합니다. -**Z-side에 문제가 있는 경우:** +**이슈가 Z-side에 있는 경우:** 1. A-side 기여자가 DZX 링크에 대한 티켓을 생성합니다. 2. 티켓을 DZ/Malbeclabs에 할당합니다. -3. DZ/Malbeclabs가 조사하고 필요 시 Z-side 기여자에게 재할당합니다. +3. DZ/Malbeclabs가 조사하고 필요한 경우 Z-side 기여자에게 재할당합니다. -이 워크플로우가 제한적이라는 것을 인지하고 있습니다. 현재 Z-side 기여자는 소유하지 않은 DZX 링크에 대해 티켓을 생성할 수 없으므로, 조율이 DZ/Malbeclabs를 통해 이루어져야 합니다. DZX 링크의 양측이 독립적으로 인시던트와 유지보수를 선언할 수 있도록 개선 작업을 진행 중입니다. \ No newline at end of file +이 워크플로우가 제한적이라는 것을 인지하고 있습니다. Z-side 기여자는 현재 자신이 소유하지 않은 DZX 링크에 대해 티켓을 생성할 수 없으며, 이는 조율이 DZ/Malbeclabs를 통해 이루어져야 함을 의미합니다. DZX 링크의 양측 모두 독립적으로 인시던트와 유지보수를 선언할 수 있도록 개선 작업을 진행하고 있습니다. \ No newline at end of file diff --git a/docs/contribute-ops-management.pt.md b/docs/contribute-ops-management.pt.md index 89c266f..fa69f84 100644 --- a/docs/contribute-ops-management.pt.md +++ b/docs/contribute-ops-management.pt.md @@ -6,18 +6,18 @@ O portal de Gestão OPS do DoubleZero é onde os contribuidores registam e acomp ## Portal vs Slack -O portal de Gestão OPS e o Slack funcionam em conjunto. Todos os incidentes e manutenções são rastreados como tickets, acessíveis através do portal ou da API. Cada ticket notifica automaticamente os canais Slack corretos e oferece a todos os contribuidores uma visão partilhada do que está a acontecer na rede. O Slack é onde a conversa acontece: partilhar logs, coordenar com outros contribuidores e colaborar em problemas ativos. +O portal de Gestão OPS e o Slack trabalham em conjunto. Todos os incidentes e manutenções são rastreados como tickets, acessíveis através do portal ou da API. Cada ticket notifica automaticamente os canais Slack corretos e dá a cada contribuidor uma visão partilhada do que está a acontecer na rede. O Slack é onde a conversa acontece: partilhar logs, coordenar com outros contribuidores e colaborar em problemas ativos. -Os tickets são o registo canónico, quer sejam criados pelo portal ou pela API. As threads do Slack não são: não atualizam o estado do ticket e não são armazenadas permanentemente. Mantenha sempre o estado do ticket atualizado, mesmo que a conversa esteja a decorrer no Slack. +Os tickets são o registo canónico, sejam criados pelo portal ou pela API. As threads do Slack não são: elas não atualizam o estado do ticket e não são armazenadas permanentemente. Mantenha sempre o estado do ticket atualizado, mesmo que a conversa esteja a decorrer no Slack. -O portal e o Slack servem propósitos diferentes. Use ambos, mas para as finalidades certas. +O portal e o Slack servem propósitos diferentes. Use ambos, mas para as coisas certas. | Use o portal (ou API) para... | Use o Slack para... | |-------------------------------|-----------------| | Abrir, atualizar e fechar tickets | Conversa e colaboração sobre um problema ativo | | Registar transições de estado | Partilhar logs, capturas de ecrã ou iniciar uma chamada | -| Atribuir ou escalar um ticket | Chamar rapidamente a atenção para um problema | -| Definir a causa raiz no encerramento | Coordenar com outros contribuidores | +| Atribuir ou escalar um ticket | Obter atenção rápida sobre um problema | +| Definir causa raiz ao fechar | Coordenar com outros contribuidores | @@ -27,7 +27,7 @@ O portal e o Slack servem propósitos diferentes. Use ambos, mas para as finalid Complete estes passos uma vez antes de usar o portal. -### 1. Defina a Sua Chave de Ops Manager +### 1. Definir a Sua Chave de Ops Manager Registe uma pubkey de carteira Solana como a sua chave de Ops Manager. Carteiras suportadas: Phantom, Solflare, Coinbase Wallet. @@ -37,15 +37,15 @@ doublezero contributor update \ --pubkey ``` -### 2. Conecte a Sua Carteira no Portal +### 2. Conectar a Sua Carteira no Portal 1. Navegue até [https://doublezero.xyz/ops-management](https://doublezero.xyz/ops-management). 2. Clique em **Connect Your Wallet** e selecione a sua carteira. 3. Assine a mensagem para provar a propriedade da sua chave de Ops Manager. -Uma vez autenticado, a **Tabela de Rastreamento de Incidentes** é apresentada. +Após a autenticação, a **Tabela de Rastreamento de Incidentes** é apresentada. -As definições da conta estão atrás do menu **Settings** (ícone de engrenagem, canto superior direito): API Key Management, User Management e Escalation Contacts. As opções que vê dependem do seu papel. +As configurações da conta encontram-se no menu **Settings** (ícone de engrenagem, canto superior direito): API Key Management, User Management e Escalation Contacts. As opções que vê dependem do seu papel. ### 3. Criar Chaves de API (Opcional) @@ -53,7 +53,7 @@ Para acesso programático em vez do formulário web: 1. Abra o menu **Settings** (ícone de engrenagem) e escolha **API Key Management**. 2. Crie uma ou mais chaves de API. -3. Descarregue a documentação da API a partir desta página. +3. Faça download da documentação da API a partir desta página. --- @@ -69,21 +69,21 @@ Atribua a severidade com base no impacto na rede DoubleZero. Pode atualizar a se |----------|--------|----------| | `sev1` | Interrupção total ou falha grave no plano de controlo/dados sem alternativa | Largue tudo imediatamente, mesmo fora do horário de trabalho. Escale para a DoubleZero Foundation imediatamente. | | `sev2` | Impacto parcial mas substancial; serviço degradado com possível alternativa | Trate como urgente. Coordene ativamente. Resposta noturna necessária para degradação sustentada. | -| `sev3` | Impacto limitado ou sem impacto visível para o utilizador; potencial de escalar se não resolvido | Prioridade máxima durante o horário de trabalho. Monitorize de perto. Sem necessidade de escalação fora de horas, a menos que o impacto aumente. | +| `sev3` | Impacto limitado ou sem impacto visível para o utilizador; potencial de escalar se não resolvido | Prioridade máxima durante o horário de trabalho. Monitorize de perto. Não é necessária escalação fora de horas, a menos que o impacto aumente. | ??? note "Exemplos de severidade" **Exemplos Sev1** - - Mais de 10% do tráfego de utilizadores perdido (blackholed) no DoubleZero, sem alternativa para internet pública + - Mais de 10% do tráfego de utilizadores em blackhole no DoubleZero, sem alternativa para a internet pública - Mais de 80% das tentativas de onboarding, conexão ou desconexão de utilizadores a falhar - Mais de 20% dos DZDs a reportar erros de interface - Controlador a devolver configurações válidas mas incorretas aos agentes DZD **Exemplos Sev2** - - Mais de 20% dos utilizadores incapazes de enviar/receber tráfego através dos túneis DoubleZero, mas com fallback para internet pública - - 0–10% do tráfego de utilizadores perdido (blackholed) no DoubleZero sem alternativa + - Mais de 20% dos utilizadores incapazes de enviar/receber tráfego através dos túneis DoubleZero, mas com fallback para a internet pública + - 0–10% do tráfego de utilizadores em blackhole no DoubleZero sem alternativa - 20–80% das novas tentativas de onboarding, conexão ou desconexão de utilizadores a falhar - Mais de 20% dos agentes de configuração a falhar na aplicação da configuração DZD - 0–20% dos DZDs a reportar erros de interface @@ -95,7 +95,7 @@ Atribua a severidade com base no impacto na rede DoubleZero. Pode atualizar a se **Exemplos Sev3** - - 0–20% dos utilizadores incapazes de enviar/receber tráfego através dos túneis DoubleZero, com fallback para internet pública + - 0–20% dos utilizadores incapazes de enviar/receber tráfego através dos túneis DoubleZero, com fallback para a internet pública - 0–20% dos DZDs a reportar erros de interface - 0–20% dos DZDs a experienciar falhas no agente de configuração - 0–20% das tentativas de onboarding, conexão ou desconexão de utilizadores a falhar @@ -103,12 +103,12 @@ Atribua a severidade com base no impacto na rede DoubleZero. Pode atualizar a se - 0–20% da recolha ou submissão de latência de internet a falhar para todos os fornecedores de dados - Bugs ou dívida técnica a causar ruído de alertas que não pode ser silenciado - DIA em baixo ou problemas de rede RPC do ledger para 0–20% dos dispositivos durante várias horas - - Problemas de baixo impacto como bugs menores, erros cosméticos ou incidentes isolados que não afetam o tráfego dos clientes - - Pequena fração de dispositivos a reportar erros intermitentes sem interrupção de serviço + - Problemas de baixo impacto como bugs menores, erros cosméticos ou incidentes isolados que não afetam o tráfego do cliente + - Pequena fração de dispositivos a reportar erros intermitentemente sem interrupção do serviço ### Abrir um Incidente -Clique em **Create New Record**, selecione Type = **Incident** no portal, ou submeta via API. +Clique em **Create New Record**, selecione Type = **Incident** no portal, ou submeta via a API. **Obrigatório:** @@ -127,20 +127,20 @@ Clique em **Create New Record**, selecione Type = **Incident** no portal, ou sub | `reporter_name` / `reporter_email` | Os seus dados de contacto | | `assignee` | Quem é responsável pela resolução | | `internal_reference` | O seu ID de ticket interno (ex.: Jira, ServiceNow) | -| `start_at` | Assume por defeito a hora de criação; editável | +| `start_at` | Por defeito é a hora de criação; editável | -Uma vez criado, uma notificação é publicada no canal Slack de incidentes dos contribuidores com o ID do ticket, severidade, dispositivos/links afetados e nome do contribuidor. +Após a criação, uma notificação é publicada no canal Slack de incidentes do contribuidor com o ID do ticket, severidade, dispositivos/links afetados e nome do contribuidor. ### Atualizar um Incidente -À medida que o incidente progride, mantenha o estado do ticket atualizado. Este é o sinal que outros contribuidores e a DZ usam para compreender o que está a ser tratado. +À medida que o incidente progride, mantenha o estado do ticket atualizado. Este é o sinal que outros contribuidores e a DZ usam para entender o que está a ser trabalhado. | Estado | Quando definir | |--------|----------------| -| `open` | Estado inicial: problema reportado, ainda não está a ser tratado | -| `acknowledged` | Viu o problema e assumiu responsabilidade | +| `open` | Estado inicial: problema reportado, ainda não a ser trabalhado | +| `acknowledged` | Viu e assumiu a responsabilidade | | `investigating` | A diagnosticar ativamente: a recolher logs, a verificar métricas | -| `mitigating` | Causa raiz conhecida ou suspeita; a aplicar correção ou solução temporária | +| `mitigating` | Causa raiz conhecida ou suspeita; a aplicar correção ou solução alternativa | | `monitoring` | Correção aplicada; a monitorizar para confirmar que se mantém | | `resolved` | Problema confirmado como resolvido; **causa raiz obrigatória** | | `closed` | Totalmente concluído; sem mais ações; **causa raiz obrigatória** | @@ -151,11 +151,11 @@ open → acknowledged → investigating → mitigating → monitoring → resolv Pode saltar estados se apropriado. Por exemplo, saltar diretamente de `open` para `investigating` se começar a trabalhar imediatamente. Use sempre o estado mais preciso para a situação atual. -Cada atualização de estado publica uma resposta na thread da notificação Slack original. +Cada atualização de estado publica uma resposta na thread da notificação original do Slack. ### Fechar um Incidente -Para mover um incidente para `resolved` ou `closed`, uma **causa raiz** deve ser definida. Pode definir a causa raiz em qualquer fase anterior se já a conhecer; torna-se obrigatória no encerramento. +Para mover um incidente para `resolved` ou `closed`, uma **causa raiz** deve ser definida. Pode definir a causa raiz em qualquer fase anterior se já a conhecer; torna-se obrigatória no fecho. | Código | Descrição | |------|-------------| @@ -163,7 +163,7 @@ Para mover um incidente para `resolved` ou `closed`, uma **causa raiz** deve ser | `software` | Correção, atualização ou reinício de software ou firmware | | `configuration` | Alteração, correção ou reversão de configuração | | `capacity` | Congestionamento, limites de capacidade ou gestão de tráfego | -| `carrier` | Problema com circuito, comprimento de onda ou fornecedor de cross-connect | +| `carrier` | Problema com o fornecedor de circuito, comprimento de onda ou cross-connect | | `network_external` | Problema de rede externo fora do controlo do contribuidor | | `facility` | Problema de infraestrutura do datacenter (energia, refrigeração) | | `fiber_cut` | Dano físico na fibra reparado | @@ -178,11 +178,11 @@ Para mover um incidente para `resolved` ou `closed`, uma **causa raiz** deve ser ## Manutenção -Um registo de manutenção é uma atividade planeada, com limite temporal, que pode afetar a disponibilidade. Crie-o antecipadamente para que outros contribuidores possam ver e evitar janelas em conflito. +Um registo de manutenção é uma atividade planeada e limitada no tempo que pode afetar a disponibilidade. Crie-o antecipadamente para que outros contribuidores possam ver e evitar janelas em conflito. ### Agendar Manutenção -Clique em **Create New Record** > **Maintenance** no portal, ou submeta via API. +Clique em **Create New Record** > **Maintenance** no portal, ou submeta via a API. **Obrigatório:** @@ -190,11 +190,14 @@ Clique em **Create New Record** > **Maintenance** no portal, ou submeta via API. |-------|-------------| | `title` | Resumo curto (máximo 100 caracteres) | | `description` | Explicação detalhada (máximo 500 caracteres) | +| `severity` | `sev1`, `sev2` ou `sev3`. Defina para o impacto esperado no utilizador (ver nota abaixo). | | `start_at` | Hora de início planeada (UTC) | | `end_at` | Hora de fim planeada (UTC); deve ser posterior a `start_at` | | Dispositivo e/ou Link | Pelo menos um obrigatório. No formulário web, selecione a partir de um dropdown dos seus códigos de dispositivo e link. Ao usar a API, passe as pubkeys correspondentes como `device_pubkey` e/ou `affected_link_pubkey`. | -Uma vez criado, uma notificação é publicada no canal Slack de manutenção dos contribuidores com o ID do ticket, dispositivos/links afetados, janela planeada e nome do contribuidor. +A severidade aplica-se à manutenção da mesma forma que aos incidentes. Defina-a para o impacto no utilizador que espera durante a janela, usando os [níveis de severidade acima](#niveis-de-severidade). + +Após a criação, uma notificação é publicada no canal Slack de manutenção do contribuidor com o ID do ticket, dispositivos/links afetados, janela planeada e nome do contribuidor. ### Gerir o Estado da Manutenção @@ -209,7 +212,7 @@ Mantenha o estado atualizado à medida que a janela progride. | `cancelled` | Cancelada antes ou durante a execução | ``` -planned → in-progress → completed → closed (auto 24h after end_at) +planned → in-progress → completed → closed (auto 24h após end_at) ↓ ↓ └──────────┴──→ cancelled ``` @@ -218,7 +221,7 @@ planned → in-progress → completed → closed (auto 24h after end_at) ## Contactos de Escalação -Os contactos de escalação indicam ao DoubleZero e a outros contribuidores quem contactar quando a sua parte da rede tem um problema. Configura os seus próprios contactos para a sua organização. Um contacto pode ser uma pessoa ou uma equipa, como o seu NOC. Cada contacto tem uma ou mais formas de ser alcançado e um horário de quando está de serviço. +Os contactos de escalação informam o DoubleZero e outros contribuidores quem contactar quando a sua parte da rede tem um problema. Configura os seus próprios contactos para a sua organização. Um contacto pode ser uma pessoa ou uma equipa, como o seu NOC. Cada contacto tem uma ou mais formas de ser alcançado e um horário para quando está de serviço. Abra o menu **Settings** (ícone de engrenagem) e escolha **Escalation Contacts**. Apenas ops managers podem adicionar ou editar contactos. @@ -230,20 +233,20 @@ Para cada contacto, defina: |-------|-------------| | Nome | Um nome para o contacto, seja uma pessoa ou uma equipa como o seu NOC | | Fuso horário | O fuso horário local, usado para ler o horário | -| Disponibilidade | **24/7**, ou uma ou mais faixas horárias semanais em que o contacto está de serviço | +| Disponibilidade | **24/7**, ou um ou mais intervalos semanais quando o contacto está de serviço | | Métodos de contacto | Uma ou mais formas de alcançar o contacto, por ordem de prioridade | Os métodos de contacto suportados são email, telefone, Slack, Telegram e WhatsApp. A ordem importa: o primeiro método é o que deve ser tentado primeiro. ### Disponibilidade e Lacunas de Cobertura -Um contacto está disponível permanentemente (24/7) ou disponível durante faixas horárias semanais que define, por exemplo de segunda a sexta, das 09:00 às 17:00. As faixas são introduzidas no fuso horário local do contacto e apresentadas em UTC, de modo que o horário de verão é tratado automaticamente. +Um contacto está disponível permanentemente (24/7) ou disponível durante intervalos semanais que define, por exemplo segunda a sexta, 09:00 às 17:00. Os intervalos são introduzidos no fuso horário local do contacto e apresentados em UTC, para que a hora de verão seja tratada automaticamente. -A vista de **lacunas de cobertura** mostra os horários de cada semana em que ninguém da sua organização está de serviço. Use-a para encontrar e colmatar lacunas. +A vista de **lacunas de cobertura** mostra os horários em cada semana em que ninguém da sua organização está de serviço. Use-a para encontrar e eliminar lacunas. ### Janelas de Rotação -A semana é dividida em janelas de meia hora. Para cada janela pode definir a ordem em que os seus contactos são alcançados. Isto permite gerir uma rotação de serviço sem editar cada contacto individualmente. +A semana é dividida em janelas de meia hora. Para cada janela pode definir a ordem em que os seus contactos são alcançados. Isto permite-lhe executar uma rotação de serviço sem editar cada contacto. ### Visibilidade @@ -251,7 +254,7 @@ Controla quem pode ver os seus contactos. O DoubleZero pode sempre vê-los. Esco | Definição | Quem mais pode ver os seus contactos | |---------|-------------------------------| -| Apenas DoubleZero (predefinição) | Nenhum outro contribuidor | +| Apenas DoubleZero (padrão) | Nenhum outro contribuidor | | Todos | Todos os contribuidores | | Alguns contribuidores | Apenas os contribuidores que selecionar | @@ -261,7 +264,7 @@ A sua própria equipa pode sempre ver os seus contactos. A visibilidade é defin ## Gestão de Utilizadores -Por predefinição, a sua chave de Ops Manager é a única conta que pode agir em nome da sua organização. Pode adicionar membros da equipa para que mais do que uma pessoa possa gerir os seus tickets. +Por defeito, a sua chave de Ops Manager é a única conta que pode agir em nome da sua organização. Pode adicionar membros da equipa para que mais do que uma pessoa possa gerir os seus tickets. Abra o menu **Settings** (ícone de engrenagem) e escolha **User Management**. Apenas ops managers podem adicionar ou remover membros da equipa. @@ -270,7 +273,7 @@ Para cada membro da equipa, defina: | Campo | Descrição | |-------|-------------| | Nome | O nome da pessoa | -| Pubkey da carteira | A carteira Solana com a qual iniciam sessão | +| Wallet pubkey | A carteira Solana com que iniciam sessão | | Nível de acesso | **Read** ou **Read-write** | Níveis de acesso: @@ -290,7 +293,7 @@ Cada membro da equipa inicia sessão com a sua própria carteira, da mesma forma - Atribuir tickets a si próprios ou escalar para DZ/Malbeclabs. - Ver todos os tickets de todos os contribuidores. - Adicionar membros da equipa e definir o seu nível de acesso (apenas ops managers). -- Gerir contactos de escalação da sua organização (apenas ops managers). +- Gerir contactos de escalação para a sua organização (apenas ops managers). ### O Que os Admins DZ/Malbeclabs Podem Fazer @@ -300,9 +303,9 @@ Cada membro da equipa inicia sessão com a sua própria carteira, da mesma forma ### Propriedade de Links DZX -Os links DZX conectam dispositivos de dois contribuidores diferentes. O contribuidor do **lado A** (primeiro dispositivo no nome do link) é o proprietário do link e é o único que pode criar tickets para ele. +Os links DZX conectam dispositivos de dois contribuidores diferentes. O contribuidor do **lado A** (primeiro dispositivo no nome do link) é proprietário do link e é o único que pode criar tickets para ele. -**Exemplo:** Para o link `deviceA:deviceB`, o contribuidor que detém `deviceA` é o proprietário do link. +**Exemplo:** Para o link `deviceA:deviceB`, o contribuidor que é proprietário do `deviceA` é proprietário do link. **Se o problema está no lado Z:** @@ -310,4 +313,4 @@ Os links DZX conectam dispositivos de dois contribuidores diferentes. O contribu 2. Atribui o ticket a DZ/Malbeclabs. 3. DZ/Malbeclabs investiga e reatribui ao contribuidor do lado Z se necessário. -Reconhecemos que este fluxo de trabalho é limitado. Atualmente, os contribuidores do lado Z não podem criar tickets para links DZX que não possuem, o que significa que a coordenação tem de passar por DZ/Malbeclabs. Estamos a trabalhar para melhorar isto de modo que ambos os lados de um link DZX possam declarar incidentes e manutenções de forma independente. \ No newline at end of file +Reconhecemos que este fluxo de trabalho é limitado. Os contribuidores do lado Z atualmente não podem criar tickets para links DZX que não possuem, o que significa que a coordenação tem de passar por DZ/Malbeclabs. Estamos a trabalhar para melhorar isto para que ambos os lados de um link DZX possam declarar incidentes e manutenções de forma independente. \ No newline at end of file diff --git a/docs/contribute-ops-management.zh.md b/docs/contribute-ops-management.zh.md index ac65dd2..716cbff 100644 --- a/docs/contribute-ops-management.zh.md +++ b/docs/contribute-ops-management.zh.md @@ -1,29 +1,29 @@ # OPS 管理 -DoubleZero OPS 管理门户是贡献者记录和跟踪事件（计划外中断）和维护（计划性工作）的地方。所有工单对所有贡献者可见。 +DoubleZero OPS 管理门户是贡献者记录和跟踪事故（计划外中断）及维护（计划内工作）的地方。所有工单对所有贡献者可见。 **门户：** [https://doublezero.xyz/ops-management](https://doublezero.xyz/ops-management) ## 门户与 Slack -OPS 管理门户和 Slack 协同工作。所有事件和维护都以工单形式跟踪，可通过门户或 API 访问。每个工单会自动通知对应的 Slack 频道，并为每个贡献者提供网络当前状况的共享视图。Slack 是进行对话的地方：共享日志、与其他贡献者协调以及协作处理活跃问题。 +OPS 管理门户和 Slack 协同工作。所有事故和维护均以工单形式进行跟踪，可通过门户或 API 访问。每张工单会自动通知相应的 Slack 频道，并为每位贡献者提供网络当前状况的共享视图。Slack 是对话发生的地方：共享日志、与其他贡献者协调以及协作处理活跃问题。 -工单是权威记录，无论是通过门户还是 API 创建。Slack 对话则不是：它们不会更新工单状态，也不会永久存储。即使对话发生在 Slack 中，也请始终保持工单状态为最新。 +工单是规范记录，无论是通过门户还是 API 创建。Slack 线程不是：它们不会更新工单状态，也不会永久存储。即使对话在 Slack 中进行，也请始终保持工单状态为最新。 -门户和 Slack 服务于不同目的。两者都要使用，但要用在正确的场景。 +门户和 Slack 服务于不同的目的。两者都要使用，但要用在正确的场景。 -| 使用门户（或 API）进行... | 使用 Slack 进行... | +| 使用门户（或 API）用于... | 使用 Slack 用于... | |-------------------------------|-----------------| -| 创建、更新和关闭工单 | 就活跃问题进行对话和协作 | +| 开启、更新和关闭工单 | 针对活跃问题的对话和协作 | | 记录状态变更 | 共享日志、截图或发起通话 | -| 分配或升级工单 | 快速引起他人关注某个问题 | +| 分配或升级工单 | 快速引起他人关注问题 | | 关闭时设置根本原因 | 与其他贡献者协调 | --- -## 入门准备 +## 入门引导 在使用门户之前，请完成以下一次性步骤。 @@ -41,72 +41,72 @@ doublezero contributor update \ 1. 导航至 [https://doublezero.xyz/ops-management](https://doublezero.xyz/ops-management)。 2. 点击 **Connect Your Wallet** 并选择您的钱包。 -3. 签署消息以证明您对 Ops Manager 密钥的所有权。 +3. 签署消息以证明您拥有该 Ops Manager 密钥。 -认证完成后，**Incident Tracking Table** 将显示。 +认证完成后，将显示 **事故跟踪表**。 -账户设置位于 **Settings** 菜单（右上角齿轮图标）下方：API Key Management、User Management 和 Escalation Contacts。您看到的选项取决于您的角色。 +帐户设置位于 **Settings** 菜单（右上角齿轮图标）下：API Key Management、User Management 和 Escalation Contacts。您看到的选项取决于您的角色。 ### 3. 创建 API 密钥（可选） 如需通过编程方式访问而非使用 Web 表单： -1. 打开 **Settings** 菜单（齿轮图标）并选择 **API Key Management**。 +1. 打开 **Settings** 菜单（齿轮图标），选择 **API Key Management**。 2. 创建一个或多个 API 密钥。 -3. 从此页面下载 API 文档。 +3. 从该页面下载 API 文档。 --- -## 事件 +## 事故 -事件是计划外的影响服务的事件。 +事故是指计划外的影响服务的事件。 ### 严重级别 -根据对 DoubleZero 网络的影响分配严重级别。您可以随着情况变化更新严重级别。 +根据对 DoubleZero 网络的影响分配严重级别。随着情况的发展，您可以更新严重级别。 | 严重级别 | 影响 | 响应 | |----------|--------|----------| -| `sev1` | 完全中断或重大控制/数据平面故障，无备用方案 | 立即放下一切工作，即使在非工作时间。立即升级至 DoubleZero Foundation。 | -| `sev2` | 部分但重大影响；服务降级，可能有备用方案 | 视为紧急事项。积极协调。持续降级需要夜间响应。 | -| `sev3` | 有限或无用户可感知的影响；如未解决可能升级 | 工作时间内的最高优先级。密切监控。除非影响加大，否则无需非工作时间升级。 | +| `sev1` | 完全中断或重大控制/数据平面故障且无备用方案 | 立即放下一切处理，即使在工作时间之外。立即升级至 DoubleZero Foundation。 | +| `sev2` | 部分但严重的影响；服务降级，可能有备用方案 | 视为紧急处理。积极协调。持续降级需要夜间响应。 | +| `sev3` | 有限或无用户可见影响；如未解决可能升级 | 工作时间内最高优先级。密切监控。除非影响加大，否则无需下班后升级。 | ??? note "严重级别示例" **Sev1 示例** - - 超过 10% 的用户流量在 DoubleZero 上被丢弃，无法回退到公共互联网 - - 超过 80% 的用户上线、连接或断开尝试失败 + - 超过 10% 的用户流量在 DoubleZero 上被黑洞丢弃，无法回退到公共互联网 + - 超过 80% 的用户注册、连接或断开尝试失败 - 超过 20% 的 DZD 报告接口错误 - Controller 向 DZD 代理返回有效但不正确的配置 **Sev2 示例** - 超过 20% 的用户无法通过 DoubleZero 隧道发送/接收流量，但可回退到公共互联网 - - 0–10% 的用户流量在 DoubleZero 上被丢弃且无备用方案 - - 20–80% 的新用户上线、连接或断开尝试失败 + - 0–10% 的用户流量在 DoubleZero 上被黑洞丢弃且无备用方案 + - 20–80% 的新用户注册、连接或断开尝试失败 - 超过 20% 的配置代理无法应用 DZD 配置 - 0–20% 的 DZD 报告接口错误 - 上游问题导致可观测性丧失（监控/告警中断） - 链上数据管道中断或产生不正确的数据 - - 超过 20% 的互联网延迟采集或提交失败 + - 超过 20% 的互联网延迟数据采集或提交失败 - DZD 代理无法访问 Controller - - Controller 向 DZD 返回无效配置且不会被应用 + - Controller 向 DZD 返回不会被应用的无效配置 **Sev3 示例** - - 0–20% 的用户无法通过 DoubleZero 隧道发送/接收流量，可回退到公共互联网 + - 0–20% 的用户无法通过 DoubleZero 隧道发送/接收流量，但可回退到公共互联网 - 0–20% 的 DZD 报告接口错误 - - 0–20% 的 DZD 遇到配置代理故障 - - 0–20% 的用户上线、连接或断开尝试失败 - - 单个数据提供商超过 20% 的互联网延迟采集或提交失败 - - 所有数据提供商 0–20% 的互联网延迟采集或提交失败 - - Bug 或技术债务导致无法静默的告警噪音 + - 0–20% 的 DZD 出现配置代理故障 + - 0–20% 的用户注册、连接或断开尝试失败 + - 单个数据提供商超过 20% 的互联网延迟数据采集或提交失败 + - 所有数据提供商 0–20% 的互联网延迟数据采集或提交失败 + - 缺陷或技术债务导致无法消除的告警噪音 - DIA 中断或账本 RPC 网络问题影响 0–20% 的设备持续数小时 - - 低影响问题，如小 Bug、外观错误或不影响客户流量的孤立事件 + - 低影响问题，如小型缺陷、外观错误或不影响客户流量的孤立事件 - 少量设备间歇性报告错误但未造成服务中断 -### 创建事件 +### 开启事故 点击 **Create New Record**，在门户上选择 Type = **Incident**，或通过 API 提交。 @@ -118,7 +118,7 @@ doublezero contributor update \ | `description` | 详细说明（最多 500 个字符） | | `severity` | `sev1`、`sev2` 或 `sev3` | | `status` | 创建时不能设置为终态（`resolved`、`closed`） | -| 设备和/或链路 | 至少需要一个。在 Web 表单上，从下拉列表中选择您的设备和链路代码。使用 API 时，将对应的公钥作为 `device_pubkey` 和/或 `affected_link_pubkey` 传递。 | +| Device 和/或 Link | 至少需要一个。在 Web 表单中，从您的设备和链路代码的下拉列表中选择。使用 API 时，传递对应的公钥作为 `device_pubkey` 和/或 `affected_link_pubkey`。 | **可选：** @@ -129,58 +129,58 @@ doublezero contributor update \ | `internal_reference` | 您的内部工单 ID（例如 Jira、ServiceNow） | | `start_at` | 默认为创建时间；可编辑 | -创建后，将在贡献者事件 Slack 频道中发布通知，包含工单 ID、严重级别、受影响的设备/链路和贡献者名称。 +创建后，将在贡献者事故 Slack 频道中发布通知，包含工单 ID、严重级别、受影响的设备/链路和贡献者名称。 -### 更新事件 +### 更新事故 -随着事件进展，请保持工单状态为最新。这是其他贡献者和 DZ 了解正在处理什么问题的信号。 +随着事故的进展，请保持工单状态为最新。这是其他贡献者和 DZ 了解正在处理什么的信号。 | 状态 | 何时设置 | |--------|----------------| | `open` | 初始状态：问题已报告，尚未开始处理 | -| `acknowledged` | 您已看到并承担责任 | +| `acknowledged` | 您已看到并接手负责 | | `investigating` | 正在积极诊断：收集日志、检查指标 | | `mitigating` | 根本原因已知或疑似；正在应用修复或变通方案 | -| `monitoring` | 修复已应用；正在观察以确认是否有效 | -| `resolved` | 问题已确认修复；**需要填写根本原因** | -| `closed` | 完全结束；无需进一步操作；**需要填写根本原因** | +| `monitoring` | 修复已应用；观察确认是否持续有效 | +| `resolved` | 问题已确认修复；**必须填写根本原因** | +| `closed` | 完全完成；无需进一步操作；**必须填写根本原因** | ``` open → acknowledged → investigating → mitigating → monitoring → resolved → closed ``` -如果合适，可以跳过某些状态。例如，如果您立即开始处理，可以直接从 `open` 跳转到 `investigating`。始终使用最准确反映当前状态的状态。 +如果合适，您可以跳过某些状态。例如，如果您立即开始处理，可以直接从 `open` 跳到 `investigating`。始终使用最能准确反映当前状态的状态。 -每次状态更新都会在原始 Slack 通知线程中发布一条回复。 +每次状态更新都会在原始 Slack 通知线程中发布回复。 -### 关闭事件 +### 关闭事故 -要将事件移至 `resolved` 或 `closed` 状态，必须设置**根本原因**。如果您已经知道根本原因，可以在更早的阶段设置；在关闭时它是强制性的。 +要将事故移至 `resolved` 或 `closed`，必须设置 **根本原因**。如果您已经知道根本原因，可以在更早的阶段设置；在关闭时它变为必填项。 | 代码 | 描述 | |------|-------------| -| `hardware` | 硬件维修、更换或升级（SFP、NIC、线缆、设备） | +| `hardware` | 硬件修复、更换或升级（SFP、NIC、线缆、设备） | | `software` | 软件或固件修复、更新或重启 | | `configuration` | 配置变更、修复或回滚 | | `capacity` | 拥塞、容量限制或流量管理 | -| `carrier` | 电路、波长或交叉连接提供商问题 | -| `network_external` | 贡献者控制范围外的外部网络问题 | +| `carrier` | 线路、波长或交叉连接提供商问题 | +| `network_external` | 贡献者控制范围之外的外部网络问题 | | `facility` | 数据中心基础设施问题（电力、冷却） | | `fiber_cut` | 物理光纤损坏已修复 | | `security` | 安全事件已缓解 | | `human_error` | 操作失误已纠正 | | `false_positive` | 调查后未发现实际问题 | -| `duplicate` | 已在另一个工单中跟踪 | -| `self_resolved` | 问题在无人干预的情况下自行解决 | +| `duplicate` | 已在另一张工单中跟踪 | +| `self_resolved` | 问题在无干预的情况下自行解决 | | `dz_managed` | DoubleZero 管理的软件组件问题（activator、controller 等） | --- ## 维护 -维护记录是可能影响可用性的计划性、有时间限制的活动。请提前创建，以便其他贡献者可以查看并避免窗口冲突。 +维护记录是可能影响可用性的计划内、有时间限制的活动。请提前创建，以便其他贡献者可以查看并避免窗口冲突。 -### 计划维护 +### 安排维护 在门户上点击 **Create New Record** > **Maintenance**，或通过 API 提交。 @@ -190,23 +190,26 @@ open → acknowledged → investigating → mitigating → monitoring → resolv |-------|-------------| | `title` | 简短摘要（最多 100 个字符） | | `description` | 详细说明（最多 500 个字符） | +| `severity` | `sev1`、`sev2` 或 `sev3`。设置为预期的用户影响（见下方说明）。 | | `start_at` | 计划开始时间（UTC） | | `end_at` | 计划结束时间（UTC）；必须晚于 `start_at` | -| 设备和/或链路 | 至少需要一个。在 Web 表单上，从下拉列表中选择您的设备和链路代码。使用 API 时，将对应的公钥作为 `device_pubkey` 和/或 `affected_link_pubkey` 传递。 | +| Device 和/或 Link | 至少需要一个。在 Web 表单中，从您的设备和链路代码的下拉列表中选择。使用 API 时，传递对应的公钥作为 `device_pubkey` 和/或 `affected_link_pubkey`。 | + +严重级别对维护的适用方式与事故相同。根据您预期在窗口期间对用户的影响进行设置，使用[上述严重级别](#严重级别)。 创建后，将在贡献者维护 Slack 频道中发布通知，包含工单 ID、受影响的设备/链路、计划窗口和贡献者名称。 ### 管理维护状态 -随着维护窗口的推进，请保持状态为最新。 +随着窗口的推进，请保持状态为最新。 | 状态 | 何时设置 | |--------|----------------| -| `planned` | 已计划，尚未开始 | +| `planned` | 已安排，尚未开始 | | `in-progress` | 工作已开始 | | `completed` | 工作已成功完成 | -| `closed` | 在 `end_at` 后 24 小时自动设置 | -| `cancelled` | 在执行之前或期间取消 | +| `closed` | `end_at` 后 24 小时自动设置 | +| `cancelled` | 在执行前或执行期间取消 | ``` planned → in-progress → completed → closed (auto 24h after end_at) @@ -220,7 +223,7 @@ planned → in-progress → completed → closed (auto 24h after end_at) 升级联系人告诉 DoubleZero 和其他贡献者，当您负责的网络部分出现问题时应联系谁。您为自己的组织设置联系人。联系人可以是个人或团队，例如您的 NOC。每个联系人有一种或多种联系方式以及值班时间表。 -打开 **Settings** 菜单（齿轮图标）并选择 **Escalation Contacts**。只有 ops manager 可以添加或编辑联系人。 +打开 **Settings** 菜单（齿轮图标），选择 **Escalation Contacts**。只有 ops manager 可以添加或编辑联系人。 ### 添加联系人 @@ -229,21 +232,21 @@ planned → in-progress → completed → closed (auto 24h after end_at) | 字段 | 描述 | |-------|-------------| | Name | 联系人名称，可以是个人或团队（如您的 NOC） | -| Timezone | 当地时区，用于解读时间表 | -| Availability | **24/7**，或一个或多个每周值班时间段 | -| Contact methods | 一种或多种联系方式，按优先级排序 | +| Timezone | 本地时区，用于解读时间表 | +| Availability | **24/7**，或联系人值班的一个或多个每周时间段 | +| Contact methods | 一种或多种联系方式，按优先级排列 | -支持的联系方式包括电子邮件、电话、Slack、Telegram 和 WhatsApp。顺序很重要：第一种方式是首先尝试的方式。 +支持的联系方式包括电子邮件、电话、Slack、Telegram 和 WhatsApp。顺序很重要：第一种方式是首先尝试的。 -### 可用性和覆盖空白 +### 可用性和覆盖缺口 -联系人要么全天候（24/7）可用，要么在您定义的每周时间段内可用，例如周一至周五，09:00 至 17:00。时间段以联系人的当地时区输入，并以 UTC 显示，因此夏令时会自动处理。 +联系人可以全天候（24/7）可用，也可以在您定义的每周时间段内可用，例如周一至周五 09:00 至 17:00。时间段以联系人的本地时区输入并以 UTC 显示，因此夏令时会自动处理。 -**coverage gaps**（覆盖空白）视图显示每周您的组织中无人值班的时间段。使用它来发现并填补空白。 +**覆盖缺口** 视图显示每周您的组织中无人值班的时间段。使用它来发现并填补缺口。 -### 轮换窗口 +### 轮值窗口 -一周被分为半小时的窗口。对于每个窗口，您可以设置联系人的联系顺序。这使您可以运行值班轮换而无需编辑每个联系人。 +一周被分成半小时的窗口。对于每个窗口，您可以设置联系人被联系的顺序。这让您无需编辑每个联系人即可运行值班轮换。 ### 可见性 @@ -251,32 +254,32 @@ planned → in-progress → completed → closed (auto 24h after end_at) | 设置 | 还有谁可以看到您的联系人 | |---------|-------------------------------| -| 仅 DoubleZero（默认） | 没有其他贡献者 | +| 仅 DoubleZero（默认） | 其他贡献者不可见 | | 所有人 | 所有贡献者 | | 部分贡献者 | 仅您选择的贡献者 | -您自己的团队始终可以看到您的联系人。可见性为整个组织统一设置，适用于您的所有联系人。 +您自己的团队始终可以看到您的联系人。可见性为整个组织设置一次，适用于您的所有联系人。 --- ## 用户管理 -默认情况下，您的 Ops Manager 密钥是唯一能代表您的组织操作的账户。您可以添加团队成员，使多人能够管理您的工单。 +默认情况下，您的 Ops Manager 密钥是唯一可以代表您的组织进行操作的帐户。您可以添加团队成员，以便多人管理您的工单。 -打开 **Settings** 菜单（齿轮图标）并选择 **User Management**。只有 ops manager 可以添加或移除团队成员。 +打开 **Settings** 菜单（齿轮图标），选择 **User Management**。只有 ops manager 可以添加或移除团队成员。 为每个团队成员设置： | 字段 | 描述 | |-------|-------------| -| Name | 该人员的姓名 | +| Name | 此人的姓名 | | Wallet pubkey | 用于登录的 Solana 钱包 | | Access level | **Read** 或 **Read-write** | 访问级别： - **Read**：可以查看工单和升级联系人，并创建只读 API 密钥。不能创建、更新或关闭工单。 -- **Read-write**：拥有创建、更新和关闭工单的完整权限，可以创建任何级别的 API 密钥。 +- **Read-write**：拥有创建、更新和关闭工单的完整权限，并可以创建任何级别的 API 密钥。 每个团队成员使用自己的钱包登录，方式与您连接 Ops Manager 密钥时相同。 @@ -289,8 +292,8 @@ planned → in-progress → completed → closed (auto 24h after end_at) - 仅为自己的设备和链路创建和管理工单。 - 将工单分配给自己或升级至 DZ/Malbeclabs。 - 查看所有贡献者的所有工单。 -- 添加团队成员并设置其访问级别（仅限 ops manager）。 -- 管理其组织的升级联系人（仅限 ops manager）。 +- 添加团队成员并设置其访问级别（仅 ops manager）。 +- 管理其组织的升级联系人（仅 ops manager）。 ### DZ/Malbeclabs 管理员可以做什么 @@ -300,14 +303,14 @@ planned → in-progress → completed → closed (auto 24h after end_at) ### DZX 链路所有权 -DZX 链路连接来自两个不同贡献者的设备。**A 侧**贡献者（链路名称中的第一个设备）拥有该链路，是唯一可以为其创建工单的贡献者。 +DZX 链路连接来自两个不同贡献者的设备。**A 侧** 贡献者（链路名称中的第一个设备）拥有该链路，是唯一可以为其创建工单的人。 **示例：** 对于链路 `deviceA:deviceB`，拥有 `deviceA` 的贡献者拥有该链路。 -**如果问题在 Z 侧：** +**如果问题出在 Z 侧：** 1. A 侧贡献者为 DZX 链路创建工单。 2. 将工单分配给 DZ/Malbeclabs。 3. DZ/Malbeclabs 进行调查，如有需要则重新分配给 Z 侧贡献者。 -我们认识到此工作流程存在局限性。Z 侧贡献者目前无法为其不拥有的 DZX 链路创建工单，这意味着协调必须通过 DZ/Malbeclabs 进行。我们正在努力改进，使 DZX 链路的双方都能独立声明事件和维护。 \ No newline at end of file +我们认识到此工作流程存在局限性。Z 侧贡献者目前无法为其不拥有的 DZX 链路创建工单，这意味着协调必须通过 DZ/Malbeclabs 进行。我们正在努力改进此功能，使 DZX 链路的双方都能独立声明事故和维护。 \ No newline at end of file