SDK de Go: analíticas, DNS y dominios

c.Apps.Network funciona solo con aplicaciones web. Todos los métodos reciben primero ctx y el id de la aplicación. Cada fragmento de abajo se ejecuta por sí solo dentro de este programa: pega uno a la vez en main y ejecuta goimports (consulta Ejecutar los ejemplos).

package main

import (
	"context"
	"os"
	"time"

	"github.com/squarecloudofc/sdk-api-go/v3"
)

var (
	ctx   = context.Background()
	c     = squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY"))
	appID = "abc123def456abc123def456"
	end   = time.Now()
	start = end.Add(-24 * time.Hour) // the last 24 hours
)

func main() {
	// Paste one snippet here, then run goimports.
}

Ventanas de tiempo

Analytics, Errors, Logs y Performance reciben un start y un end, cada uno un time.Time (enviado como RFC 3339 en UTC). El programa de arriba los define como las últimas 24 horas. Una ventana abarca como máximo 7 días, y start se ajusta a la fecha de creación de la aplicación. Una ventana no válida da 400 INVALID_TIME_RANGE. Los resultados se almacenan en caché en intervalos de 5 minutos. Los fallos de caché de estos cuatro métodos comparten un límite de 20 peticiones cada 60 segundos por cuenta: superarlo da 429 RATE_LIMITED.

Analíticas

Network.Analytics(ctx, appID, start, end, filters) devuelve los totales de tráfico y sus desgloses como un *NetworkAnalytics. Devuelve nil (y un error nil) para una ventana sin tráfico. Pasa un squarecloud.AnalyticsFilters{} vacío para no aplicar filtros.

analytics, err := c.Apps.Network.Analytics(ctx, appID, start, end, squarecloud.AnalyticsFilters{})
if err != nil {
	log.Fatal(err)
}

if analytics != nil {
	fmt.Println(analytics.Visits)    // []AnalyticsTimeBucket: Date, Visits, Requests, Bytes
	fmt.Println(analytics.Countries) // []AnalyticsBucket: Type ("BR"), Visits, Requests, Bytes
}

Los desgloses son Countries, Devices, OS, Browsers, Protocols, Methods, Paths, Referers, Providers, IPs, StatusCodes, Bots y ContentTypes (en JSON countries, …, status_codes, bots, content_types). Cada grupo tiene Type, Visits, Requests y Bytes (int64).

Filtros

Los filtros acotan todos los desgloses. Cada uno recibe el valor exacto de Type de su desglose. Un campo vacío no se envía:

brazil, err := c.Apps.Network.Analytics(ctx, appID, start, end, squarecloud.AnalyticsFilters{
	Country:  "BR",
	Path:     "/api",
	Provider: "GOOGLE (15169)",
})
if err != nil {
	log.Fatal(err)
}

if brazil != nil {
	fmt.Println(brazil.Paths)
}

Filtro	Ejemplo
`Country`	`"BR"` (código de 2 letras)
`IP`	`"203.0.113.7"`
`Path`	`"/api"` (prefijo de ruta)
`Status`	`"404"`
`OS`, `Browser`, `Protocol`, `Bot`	El `Type` del desglose
`Referer`	`"Direct"` significa sin referer
`Provider`	`"NAME (ASN)"`, p. ej. `"GOOGLE (15169)"`
`ContentType`	El `Type` del desglose

Un filtro no válido da 400 INVALID_FILTER.

Errores

Network.Errors(ctx, appID, start, end, include4xx) devuelve las respuestas 5xx de la ventana, más las 4xx cuando include4xx es true. Devuelve nil para una ventana vacía.

errs, err := c.Apps.Network.Errors(ctx, appID, start, end, true)
if err != nil {
	log.Fatal(err)
}

if errs != nil {
	fmt.Println(errs.Summary.Total, errs.Summary.ByClass) // ByClass: map[string]int64 with "4xx", "5xx"
	fmt.Println(errs.TopPaths)
}

Logs de peticiones

Network.Logs(ctx, appID, start, end) devuelve peticiones individuales con detalles del cliente, la petición y la respuesta. Disponible en los planes Pro y Enterprise (en caso contrario, 403 UPGRADE_REQUIRED).

logs, err := c.Apps.Network.Logs(ctx, appID, start, end)
if err != nil {
	log.Fatal(err)
}
for _, l := range logs {
	fmt.Println(l.Timestamp, l.Request.Method, l.Request.Path, l.Response.Status)
}

Los campos que la API puede enviar como null son punteros (Client.IP, Client.Country, Request.Query, Request.Referer, Response.Cache, …).

Rendimiento

Network.Performance(ctx, appID, start, end) devuelve percentiles de latencia (P50, P95, P99, en ms) en el edge y en el origen, por país, por ubicación y para las rutas más lentas. Devuelve nil para una ventana vacía. Disponible en los planes Pro y Enterprise. Cada percentil es un *float64, nil cuando no hubo peticiones que medir:

performance, err := c.Apps.Network.Performance(ctx, appID, start, end)
if err != nil {
	log.Fatal(err)
}

if performance != nil {
	if p95 := performance.Summary.Edge.P95; p95 != nil {
		fmt.Println("edge p95", *p95)
	}
	if p95 := performance.Summary.Origin.P95; p95 != nil {
		fmt.Println("origin p95", *p95)
	}
}

DNS

Network.DNS(ctx, appID) devuelve los registros DNS que necesita tu dominio personalizado, con su estado. Sin un dominio personalizado da 400 NO_CUSTOM_DOMAIN.

records, err := c.Apps.Network.DNS(ctx, appID)
if err != nil {
	log.Fatal(err)
}
for _, r := range records {
	fmt.Println(r.Type, r.Name, r.Value, r.Status) // Type: "txt" | "cname"
}

Dominio personalizado

Network.SetDomain(ctx, appID, domain) asocia un dominio personalizado (plan Standard o superior). Pasa "@" para eliminarlo.

if err := c.Apps.Network.SetDomain(ctx, appID, "www.example.com"); err != nil {
	log.Fatal(err)
}

// Remove it
if err := c.Apps.Network.SetDomain(ctx, appID, "@"); err != nil {
	log.Fatal(err)
}

Estado	Código	Cuándo
400	`INVALID_DOMAIN`	No es un nombre de dominio válido
400	`RESERVED_DOMAIN`	Un dominio de Square Cloud
403	`UPGRADE_REQUIRED`	El plan no incluye dominios personalizados
403	`LOAD_BALANCER_LIMIT_REACHED`	Se alcanzó el límite del plan de aplicaciones en este dominio
409	`DOMAIN_ALREADY_EXISTS`	El dominio pertenece a una aplicación de otra cuenta
502	`DNS_FAILED`	El proveedor del edge rechazó el dominio

Purgar la caché

Network.PurgeCache(ctx, appID) borra la caché del edge de la aplicación. Está limitado a una purga cada 60 segundos (429 KEEP_CALM).

if err := c.Apps.Network.PurgeCache(ctx, appID); err != nil {
	log.Fatal(err)
}

Errores de los métodos de analíticas

Estado	Código	Cuándo
400	`INVALID_TIME_RANGE`	`start`/`end` ausente, mal formado o invertido
400	`INVALID_FILTER`	Un filtro no respeta su formato (`Analytics`)
403	`UPGRADE_REQUIRED`	`Logs` y `Performance` fuera de Pro y Enterprise
429	`RATE_LIMITED`	Se alcanzó el límite compartido de fallos de caché
500	`UNABLE_TO_FETCH_ANALYTICS`, `UNABLE_TO_FETCH_ERRORS`, `UNABLE_TO_FETCH_PERFORMANCE`	Falló el proveedor del edge
503	`ANALYTICS_BUSY`	Las analíticas del edge están ocupadas: se reintenta automáticamente

Próximos pasos

Tiempo real

Transmite logs y estado en vivo.

Referencia de la API de red

Los endpoints REST detrás de estos métodos.

Analíticas de edge desde la CLI

Las mismas acciones desde la terminal.

CLI

VS Code

SDKs

SDK de Go: analíticas, DNS y dominios

Ventanas de tiempo

Analíticas

Filtros

Errores

Logs de peticiones

Rendimiento

DNS

Dominio personalizado

Purgar la caché

Errores de los métodos de analíticas

Próximos pasos

Tiempo real

Referencia de la API de red

Analíticas de edge desde la CLI

​Ventanas de tiempo

​Analíticas

​Filtros

​Errores

​Logs de peticiones

​Rendimiento

​DNS

​Dominio personalizado

​Purgar la caché

​Errores de los métodos de analíticas

​Próximos pasos

Tiempo real

Referencia de la API de red

Analíticas de edge desde la CLI

Ventanas de tiempo

Analíticas

Filtros

Errores

Logs de peticiones

Rendimiento

DNS

Dominio personalizado

Purgar la caché

Errores de los métodos de analíticas

Próximos pasos