diff --git a/docs/contribute-ops-management.es.md b/docs/contribute-ops-management.es.md new file mode 100644 index 0000000..9b84476 --- /dev/null +++ b/docs/contribute-ops-management.es.md @@ -0,0 +1,316 @@ +# Gestión de OPS + +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 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 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 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 | + + + +--- + +## Incorporación + +Completa estos pasos una vez antes de usar el portal. + +### 1. Configura Tu Clave de Ops Manager + +Registra una clave pública de billetera Solana como tu clave de Ops Manager. Billeteras compatibles: Phantom, Solflare, Coinbase Wallet. + +```bash +doublezero contributor update \ + --ops-manager \ + --pubkey +``` + +### 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 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**. + +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) + +Para acceso programático en lugar del formulario web: + +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. + +--- + +## 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 DoubleZero. Puedes actualizar la severidad a medida que la situación evoluciona. + +| Severidad | Impacto | Respuesta | +|----------|--------|----------| +| `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" + + **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 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 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 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 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 + - Pequeña fracción de dispositivos reportando errores intermitentemente sin interrupción del servicio + +### Abrir un Incidente + +Haz clic en **Create New Record**, selecciona Type = **Incident** en el portal, o envíalo 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 | 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:** + +| 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, severidad, dispositivos/enlaces afectados y 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 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** | + +``` +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. Siempre usa el estado más preciso para la situación actual. + +Cada actualización de estado publica una respuesta en el hilo de 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 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ó 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.) | + +--- + +## Mantenimiento + +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 Mantenimiento + +Haz clic en **Create New Record** > **Maintenance** en el portal, o envíalo 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`. 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 | 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`. | + +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). + +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. + +### Gestionar el Estado del Mantenimiento + +Mantén el estado actualizado a medida que avanza la ventana. + +| 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 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** (ícono de engranaje) y elige **Escalation Contacts**. Solo los ops managers pueden agregar o editar contactos. + +### Agregar 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 al contacto, en orden de prioridad | + +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 + +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 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 + +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 (predeterminado) | 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 agregar miembros del equipo para que más de una persona pueda gestionar tus tickets. + +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 | +| Clave pública de billetera | La billetera Solana con la que inicia 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 billetera, 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. +- 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 + +- Crear tickets para dispositivos y enlaces de cualquier contribuidor. +- Asignar o reasignar tickets entre contribuidores. +- Manejar 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. 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 new file mode 100644 index 0000000..7f5578f --- /dev/null +++ b/docs/contribute-ops-management.fr.md @@ -0,0 +1,316 @@ +# 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 a lieu : partager des logs, coordonner avec d'autres contributeurs et collaborer sur les problèmes en cours. + +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 | 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 | 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 la propriété de votre clé Ops Manager. + +Une fois authentifié, le **Tableau de suivi des incidents** s'affiche. + +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) + +Pour un accès programmatique au lieu du formulaire web : + +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. + +--- + +## Incidents + +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é à mesure que la situation évolue. + +| Sévérité | Impact | Réponse | +|----------|--------|----------| +| `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 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 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 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/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 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'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'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 interruption de 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 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` | 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 | + +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 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é comme 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 la notification Slack d'origine. + +### 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/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 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é | +| `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 (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 pour 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) | +| `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. 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 la progression de la fenêtre. + +| Statut | Quand le définir | +|--------|----------------| +| `planned` | Planifié, pas encore commencé | +| `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 | + +``` +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 en forme 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 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 le changement d'heure est géré pour vous. + +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 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é + +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 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 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 : + +| 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 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. + +--- + +## Permissions et escalade + +### Ce que les contributeurs peuvent faire + +- 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). + +### 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 du 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..6687996 --- /dev/null +++ b/docs/contribute-ops-management.it.md @@ -0,0 +1,316 @@ +# 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 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, 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. + +| 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 | Coordinamento con altri contributor | + + + +--- + +## Onboarding + +Completa questi passaggi una sola volta prima di utilizzare il portale. + +### 1. Imposta la tua chiave Ops Manager + +Registra una chiave pubblica di un wallet Solana come chiave Ops Manager. Wallet supportati: Phantom, Solflare, Coinbase Wallet. + +```bash +doublezero contributor update \ + --ops-manager \ + --pubkey +``` + +### 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. +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 visualizzate dipendono dal tuo ruolo. + +### 3. Crea chiavi API (Opzionale) + +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. +3. Scarica la documentazione API da questa pagina. + +--- + +## Incidenti + +Un incidente è un evento non pianificato che ha impatto sul 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 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 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 + - Controller che restituisce configurazioni valide ma errate agli agenti DZD + + **Esempi Sev2** + + - 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 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 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 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 **Create New Record**, seleziona Type = **Incident** sul portale, oppure invia tramite l'API. + +**Obbligatori:** + +| Campo | Descrizione | +|-------|-------------| +| `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 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 dati di contatto | +| `assignee` | Chi è responsabile della risoluzione | +| `internal_reference` | Il tuo ID ticket interno (es. Jira, ServiceNow) | +| `start_at` | Predefinito all'ora di creazione; modificabile | + +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 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 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 tenga | +| `resolved` | Problema confermato come risolto; **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 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 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 | +|--------|-------------| +| `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 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.) | + +--- + +## Manutenzione + +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 **Create New Record** > **Maintenance** sul portale, oppure invia tramite l'API. + +**Obbligatori:** + +| Campo | Descrizione | +|-------|-------------| +| `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 i codici dei tuoi dispositivi e link. Quando usi l'API, passa le pubkey corrispondenti come `device_pubkey` e/o `affected_link_pubkey`. | + +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 + +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 dopo 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 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. + +### Aggiunta di un Contatto + +Per ogni contatto, imposta: + +| Campo | Descrizione | +|-------|-------------| +| 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 Lacune di Copertura + +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 trovare e colmare le lacune. + +### 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. 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 | + +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 | +|-------|-------------| +| Nome | Il nome della persona | +| Wallet pubkey | Il wallet Solana con cui effettua l'accesso | +| Livello di accesso | **Read** o **Read-write** | + +Livelli di accesso: + +- **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 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 + +- 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 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. + +**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 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 new file mode 100644 index 0000000..0a6af3c --- /dev/null +++ b/docs/contribute-ops-management.ja.md @@ -0,0 +1,316 @@ +# 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文字） | +| `severity` | `sev1`、`sev2`、または `sev3`。予想されるユーザー影響に基づいて設定します（以下の注記を参照）。 | +| `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時間年中無休（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..35d9671 --- /dev/null +++ b/docs/contribute-ops-management.ko.md @@ -0,0 +1,316 @@ +# 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자) | +| `severity` | `sev1`, `sev2` 또는 `sev3`. 예상되는 사용자 영향에 맞게 설정합니다 (아래 참고 사항 참조). | +| `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 (end_at 이후 24시간 자동) + ↓ ↓ + └──────────┴──→ 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만 (기본값) | 다른 기여자 없음 | +| 모든 사람 | 모든 기여자 | +| 일부 기여자 | 선택한 기여자만 | + +자신의 팀은 항상 연락처를 볼 수 있습니다. 공개 범위는 조직 전체에 대해 한 번 설정되며 모든 연락처에 적용됩니다. + +--- + +## 사용자 관리 + +기본적으로 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.md b/docs/contribute-ops-management.md index da8de06..e864c08 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. @@ -188,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 @@ -214,6 +219,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 +292,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 diff --git a/docs/contribute-ops-management.pt.md b/docs/contribute-ops-management.pt.md new file mode 100644 index 0000000..fa69f84 --- /dev/null +++ b/docs/contribute-ops-management.pt.md @@ -0,0 +1,316 @@ +# 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 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, 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 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 | Obter atenção rápida sobre um problema | +| Definir causa raiz ao fechar | Coordenar com outros contribuidores | + + + +--- + +## Integração + +Complete estes passos uma vez antes de usar o portal. + +### 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. + +```bash +doublezero contributor update \ + --ops-manager \ + --pubkey +``` + +### 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. + +Após a autenticação, a **Tabela de Rastreamento de Incidentes** é apresentada. + +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) + +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. Faça download da 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. 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 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 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 + - 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 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 + - 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 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 a 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` | Por defeito é a hora de criação; editável | + +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 entender o que está a ser trabalhado. + +| Estado | Quando definir | +|--------|----------------| +| `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 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** | + +``` +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 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 fecho. + +| 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 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 | +| `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 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 a 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`. 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`. | + +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 + +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 após end_at) + ↓ ↓ + └──────────┴──→ cancelled +``` + +--- + +## Contactos de Escalaçã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. + +### 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 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 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 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-lhe executar uma rotação de serviço sem editar cada contacto. + +### 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 (padrã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 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. + +Para cada membro da equipa, defina: + +| Campo | Descrição | +|-------|-------------| +| Nome | O nome da pessoa | +| Wallet pubkey | A carteira Solana com que 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 para a 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) é proprietário do link e é o único que pode criar tickets para ele. + +**Exemplo:** Para o link `deviceA:deviceB`, o contribuidor que é proprietário do `deviceA` é 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. 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 new file mode 100644 index 0000000..716cbff --- /dev/null +++ b/docs/contribute-ops-management.zh.md @@ -0,0 +1,316 @@ +# 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 密钥。 + +认证完成后，将显示 **事故跟踪表**。 + +帐户设置位于 **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% 的互联网延迟数据采集或提交失败 + - 缺陷或技术债务导致无法消除的告警噪音 + - DIA 中断或账本 RPC 网络问题影响 0–20% 的设备持续数小时 + - 低影响问题，如小型缺陷、外观错误或不影响客户流量的孤立事件 + - 少量设备间歇性报告错误但未造成服务中断 + +### 开启事故 + +点击 **Create New Record**，在门户上选择 Type = **Incident**，或通过 API 提交。 + +**必填：** + +| 字段 | 描述 | +|-------|-------------| +| `title` | 简短摘要（最多 100 个字符） | +| `description` | 详细说明（最多 500 个字符） | +| `severity` | `sev1`、`sev2` 或 `sev3` | +| `status` | 创建时不能设置为终态（`resolved`、`closed`） | +| Device 和/或 Link | 至少需要一个。在 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 个字符） | +| `severity` | `sev1`、`sev2` 或 `sev3`。设置为预期的用户影响（见下方说明）。 | +| `start_at` | 计划开始时间（UTC） | +| `end_at` | 计划结束时间（UTC）；必须晚于 `start_at` | +| Device 和/或 Link | 至少需要一个。在 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 显示，因此夏令时会自动处理。 + +**覆盖缺口** 视图显示每周您的组织中无人值班的时间段。使用它来发现并填补缺口。 + +### 轮值窗口 + +一周被分成半小时的窗口。对于每个窗口，您可以设置联系人被联系的顺序。这让您无需编辑每个联系人即可运行值班轮换。 + +### 可见性 + +您可以控制谁能看到您的联系人。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