Cómo solucionar problemas relacionados con las etiquetas de solicitud y las etiquetas de transacción

Spanner proporciona un conjunto de tablas de estadísticas integradas para ayudarte a obtener estadísticas de tus consultas, lecturas y transacciones. Para correlacionar las estadísticas con el código de tu aplicación y mejorar la solución de problemas, puedes agregar una etiqueta (una string de formato libre) a las operaciones de lectura, consulta y transacción de Spanner en el código de tu aplicación. Estas etiquetas se propagan en tablas de estadísticas, lo que te ayuda a correlacionar y buscar en función de etiquetas.

Spanner admite dos tipos de etiquetas: las de solicitud y las de transacción. Como sugieren sus nombres, puedes agregar etiquetas de transacción a las transacciones y etiquetas de solicitudes a consultas individuales y a las APIs de lectura. Puedes configurar una etiqueta de transacción en el alcance de la transacción y configurar etiquetas de solicitud individuales para cada solicitud a la API aplicable dentro de la transacción. Las etiquetas de solicitud y de transacción que se establecen en el código de la aplicación se propagan en las columnas de las siguientes tablas de estadísticas.

Tabla de estadísticas	Tipo de etiquetas propagadas en la tabla de estadísticas
Estadísticas de consultas principales	Etiquetas de solicitud
Estadísticas de lectura principales	Etiquetas de solicitud
Principales estadísticas de transacciones	Etiquetas de transacción
Estadísticas de bloqueo de TopN	Etiquetas de transacción

Etiquetas de solicitud

Puedes agregar una etiqueta de solicitud opcional a una consulta o solicitud de lectura. Spanner agrupa las estadísticas por etiqueta de solicitud, que se puede ver en el campo REQUEST_TAG de las tablas de estadísticas de consultas y estadísticas de lectura.

Cuándo usar etiquetas de solicitud

Las siguientes son algunas de las situaciones en las que se benefician del uso de etiquetas de solicitud.

• Encontrar la fuente de una consulta o lectura problemática: Spanner recopila estadísticas de lecturas y consultas en tablas de estadísticas integradas. Cuando encuentres las consultas lentas o las lecturas que consumen mucha CPU en la tabla de estadísticas, si ya asignaste etiquetas a esas consultas, podrás identificar la fuente (aplicación/microservicio) que llama a estas operaciones en función de la información de la etiqueta.
• Identificación de lecturas o consultas en tablas de estadísticas: Asignar etiquetas de solicitud ayuda a filtrar filas en la tabla de estadísticas según las etiquetas que te interesan.
• Detectar si las consultas de una aplicación o un microservicio en particular son lentas: Las etiquetas de solicitud pueden ayudar a identificar si las consultas de una aplicación o un microservicio en particular tienen latencias más altas.
• Agrupación de estadísticas para un conjunto de lecturas o consultas: Puedes usar etiquetas de solicitud para hacer un seguimiento del rendimiento de un conjunto de operaciones de lectura o consultas similares, así como para compararlo y, además, informarlo. Por ejemplo, si varias consultas acceden a una tabla o conjunto de tablas con el mismo patrón de acceso, puedes considerar agregar la misma etiqueta a todas esas consultas para hacer un seguimiento de ellas juntas.

Cómo asignar etiquetas de solicitud

En el siguiente ejemplo, se muestra cómo configurar etiquetas de solicitud mediante las bibliotecas cliente de Spanner.

C++

void SetRequestTag(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;
  spanner::SqlStatement select(
      "SELECT SingerId, AlbumId, AlbumTitle FROM Albums");
  using RowType = std::tuple<std::int64_t, std::int64_t, std::string>;

  auto opts = google::cloud::Options{}.set<spanner::RequestTagOption>(
      "app=concert,env=dev,action=select");
  auto rows = client.ExecuteQuery(std::move(select), std::move(opts));
  for (auto& row : spanner::StreamOf<RowType>(rows)) {
    if (!row) throw std::move(row).status();
    std::cout << "SingerId: " << std::get<0>(*row)
              << " AlbumId: " << std::get<1>(*row)
              << " AlbumTitle: " << std::get<2>(*row) << "\n";
  }
}

C#

using Google.Cloud.Spanner.Data;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

public class RequestTagAsyncSample
{
    public class Album
    {
        public int SingerId { get; set; }
        public int AlbumId { get; set; }
        public string AlbumTitle { get; set; }
    }

    public async Task<List<Album>> RequestTagAsync(string projectId, string instanceId, string databaseId)
    {
        string connectionString = $"Data Source=projects/{projectId}/instances/{instanceId}/databases/{databaseId}";

        using var connection = new SpannerConnection(connectionString);
        using var cmd = connection.CreateSelectCommand(
            $"SELECT SingerId, AlbumId, AlbumTitle FROM Albums");
        // Sets the request tag to "app=concert,env=dev,action=select".
        // This request tag will only be set on this request.
        cmd.Tag = "app=concert,env=dev,action=select";

        var albums = new List<Album>();
        using var reader = await cmd.ExecuteReaderAsync();
        while (await reader.ReadAsync())
        {
            var album = new Album
            {
                SingerId = reader.GetFieldValue<int>("SingerId"),
                AlbumId = reader.GetFieldValue<int>("AlbumId"),
                AlbumTitle = reader.GetFieldValue<string>("AlbumTitle")
            };
            albums.Add(album);
            Console.WriteLine($"SingerId: {album.SingerId}, AlbumId: {album.AlbumId}, AlbumTitle: {album.AlbumTitle}");
        }
        return albums;
    }
}

Go

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/spanner"
	"google.golang.org/api/iterator"
)

// queryWithTag reads from a database with request tag set
func queryWithTag(w io.Writer, db string) error {
	// db = `projects/<project>/instances/<instance-id>/database/<database-id>`
	ctx := context.Background()
	client, err := spanner.NewClient(ctx, db)
	if err != nil {
		return err
	}
	defer client.Close()

	stmt := spanner.Statement{SQL: `SELECT SingerId, AlbumId, AlbumTitle FROM Albums`}
	iter := client.Single().QueryWithOptions(ctx, stmt, spanner.QueryOptions{RequestTag: "app=concert,env=dev,action=select"})
	defer iter.Stop()
	for {
		row, err := iter.Next()
		if err == iterator.Done {
			return nil
		}
		if err != nil {
			return err
		}
		var singerID, albumID int64
		var albumTitle string
		if err := row.Columns(&singerID, &albumID, &albumTitle); err != nil {
			return err
		}
		fmt.Fprintf(w, "%d %d %s\n", singerID, albumID, albumTitle)
	}
}

Java

static void setRequestTag(DatabaseClient databaseClient) {
  // Sets the request tag to "app=concert,env=dev,action=select".
  // This request tag will only be set on this request.
  try (ResultSet resultSet = databaseClient
      .singleUse()
      .executeQuery(
          Statement.of("SELECT SingerId, AlbumId, AlbumTitle FROM Albums"),
          Options.tag("app=concert,env=dev,action=select"))) {
    while (resultSet.next()) {
      System.out.printf(
          "SingerId: %d, AlbumId: %d, AlbumTitle: %s\n",
          resultSet.getLong(0),
          resultSet.getLong(1),
          resultSet.getString(2));
    }
  }
}

Node.js

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = 'my-project-id';
// const instanceId = 'my-instance';
// const databaseId = 'my-database';

// Imports the Google Cloud client library
const {Spanner} = require('@google-cloud/spanner');

// Creates a client
const spanner = new Spanner({
  projectId: projectId,
});

async function queryTags() {
  // Gets a reference to a Cloud Spanner instance and database.
  const instance = spanner.instance(instanceId);
  const database = instance.database(databaseId);

  // Execute a query with a request tag.
  const [albums] = await database.run({
    sql: 'SELECT SingerId, AlbumId, AlbumTitle FROM Albums',
    requestOptions: {requestTag: 'app=concert,env=dev,action=select'},
    json: true,
  });
  albums.forEach(album => {
    console.log(
      `SingerId: ${album.SingerId}, AlbumId: ${album.AlbumId}, AlbumTitle: ${album.AlbumTitle}`
    );
  });
  await database.close();
}
queryTags();

PHP

use Google\Cloud\Spanner\SpannerClient;

/**
 * Executes a read with a request tag.
 * Example:
 * ```
 * spanner_set_request_tag($instanceId, $databaseId);
 * ```
 *
 * @param string $instanceId The Spanner instance ID.
 * @param string $databaseId The Spanner database ID.
 */
function set_request_tag(string $instanceId, string $databaseId): void
{
    $spanner = new SpannerClient();
    $instance = $spanner->instance($instanceId);
    $database = $instance->database($databaseId);

    $snapshot = $database->snapshot();
    $results = $snapshot->execute(
        'SELECT SingerId, AlbumId, AlbumTitle FROM Albums',
        [
            'requestOptions' => [
                'requestTag' => 'app=concert,env=dev,action=select'
            ]
        ]
    );
    foreach ($results as $row) {
        printf('SingerId: %s, AlbumId: %s, AlbumTitle: %s' . PHP_EOL,
            $row['SingerId'], $row['AlbumId'], $row['AlbumTitle']);
    }
}

Python

# instance_id = "your-spanner-instance"
# database_id = "your-spanner-db-id"
spanner_client = spanner.Client()
instance = spanner_client.instance(instance_id)
database = instance.database(database_id)

with database.snapshot() as snapshot:
    results = snapshot.execute_sql(
        "SELECT SingerId, AlbumId, AlbumTitle FROM Albums",
        request_options={"request_tag": "app=concert,env=dev,action=select"},
    )

    for row in results:
        print("SingerId: {}, AlbumId: {}, AlbumTitle: {}".format(*row))

Rita

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client = spanner.client instance_id, database_id

client.execute(
  "SELECT SingerId, AlbumId, MarketingBudget FROM Albums",
  request_options: { tag: "app=concert,env=dev,action=select" }
).rows.each do |row|
  puts "#{row[:SingerId]} #{row[:AlbumId]} #{row[:MarketingBudget]}"
end

Cómo ver las etiquetas de solicitud en la tabla de estadísticas

La siguiente consulta muestra las estadísticas de la consulta en intervalos de 10 minutos.

SELECT t.text,
       t.request_tag,
       t.execution_count,
       t.avg_latency_seconds,
       t.avg_rows,
       t.avg_bytes
FROM SPANNER_SYS.QUERY_STATS_TOP_10MINUTE AS t
LIMIT 3;

Tomemos los siguientes datos como ejemplo de los resultados que obtenemos de nuestra consulta.

texto	request_tag	execution_count	avg_latency_seconds	avg_rows	avg_bytes
SELECT SingerId, AlbumId, AlbumTitle FROM Albums	app=concert,env=dev,action=select	212	0.025	21	2365
seleccionar * de los pedidos;	app=catalogsearch,env=dev,action=list	55	0.02	16	33.35
SELECT SingerId, FirstName, LastName FROM Singers;	[string vacía]	154	0.048	42	486.33

En esta tabla de resultados, podemos ver que, si asignaste un REQUEST_TAG para una consulta, se propaga en la tabla de estadísticas. Si no hay ninguna etiqueta de solicitud asignada, se muestra como una cadena vacía.

Para las consultas etiquetadas, las estadísticas se agregan por etiqueta (p.ej., la etiqueta de solicitud app=concert,env=dev,action=select tiene una latencia promedio de 0.025 segundos). Si no hay ninguna etiqueta asignada, las estadísticas se agregan por consulta (p.ej., la consulta de la tercera fila tiene una latencia promedio de 0.048 segundos).

Etiquetas de transacción

Se puede agregar una etiqueta de transacción opcional a transacciones individuales. Spanner agrupa las estadísticas por etiqueta de transacción, que se puede ver en el campo TRANSACTION_TAG de las tablas de estadísticas de transacciones.

Cuándo usar etiquetas de transacción

Las siguientes son algunas de las situaciones que se benefician del uso de etiquetas de transacción.

• Encuentra la fuente de una transacción problemática: Spanner recopila estadísticas de transacciones de lectura y escritura en la tabla de estadísticas de transacciones. Cuando encuentres transacciones lentas en la tabla de estadísticas de transacciones, si ya les asignaste etiquetas, puedes identificar la fuente (aplicación/microservicio) que llama a estas transacciones según la información de la etiqueta.
• Identificar transacciones en tablas de estadísticas: Asignar etiquetas de transacción ayuda a filtrar filas en la tabla de estadísticas de transacciones en función de las etiquetas que te interesan. Sin etiquetas de transacción, descubrir qué operaciones representan una estadística puede ser un proceso engorroso. Por ejemplo, para las estadísticas de transacciones, tendrías que examinar las tablas y columnas involucradas para identificar la transacción sin etiquetar.
• Detectar si las transacciones de una aplicación o un microservicio en particular son lentas: Las etiquetas de transacción pueden ayudar a identificar si las transacciones de una aplicación o un microservicio en particular tienen latencias más altas.
• Agrupación de estadísticas para un conjunto de transacciones: Puedes usar etiquetas de transacción para hacer un seguimiento de un conjunto de transacciones similares, realizar una comparación y generar informes sobre el rendimiento.
• Encontrar qué transacciones acceden a las columnas involucradas en el conflicto de bloqueo: Las etiquetas de transacción pueden ayudar a identificar transacciones individuales que causan conflictos de bloqueo en las tablas de Estadísticas de bloqueo.
• Transmitir datos de cambios de usuario fuera de Spanner mediante flujos de cambios: Los registros de datos de flujos de cambios contienen etiquetas de transacción para las transacciones que modificaron los datos del usuario. Esto permite que el lector de un flujo de cambios asocie los cambios con el tipo de transacción en función de etiquetas.

Cómo asignar etiquetas de transacción

En el siguiente ejemplo, se muestra cómo configurar etiquetas de transacción mediante las bibliotecas cliente de Spanner. Cuando usas una biblioteca cliente, puedes configurar una etiqueta de transacción al comienzo de la llamada de transacción que se aplica a todas las operaciones individuales dentro de esa transacción.

C++

void SetTransactionTag(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;
  using ::google::cloud::StatusOr;

  // Sets the transaction tag to "app=concert,env=dev". This will be
  // applied to all the individual operations inside this transaction.
  auto commit_options =
      google::cloud::Options{}.set<spanner::TransactionTagOption>(
          "app=concert,env=dev");
  auto commit = client.Commit(
      [&client](
          spanner::Transaction const& txn) -> StatusOr<spanner::Mutations> {
        spanner::SqlStatement update_statement(
            "UPDATE Venues SET Capacity = CAST(Capacity/4 AS INT64)"
            "  WHERE OutdoorVenue = false");
        // Sets the request tag to "app=concert,env=dev,action=update".
        // This will only be set on this request.
        auto update = client.ExecuteDml(
            txn, std::move(update_statement),
            google::cloud::Options{}.set<spanner::RequestTagOption>(
                "app=concert,env=dev,action=update"));
        if (!update) return std::move(update).status();

        spanner::SqlStatement insert_statement(
            "INSERT INTO Venues (VenueId, VenueName, Capacity, OutdoorVenue, "
            "                    LastUpdateTime)"
            " VALUES (@venueId, @venueName, @capacity, @outdoorVenue, "
            "         PENDING_COMMIT_TIMESTAMP())",
            {
                {"venueId", spanner::Value(81)},
                {"venueName", spanner::Value("Venue 81")},
                {"capacity", spanner::Value(1440)},
                {"outdoorVenue", spanner::Value(true)},
            });
        // Sets the request tag to "app=concert,env=dev,action=insert".
        // This will only be set on this request.
        auto insert = client.ExecuteDml(
            txn, std::move(insert_statement),
            google::cloud::Options{}.set<spanner::RequestTagOption>(
                "app=concert,env=dev,action=select"));
        if (!insert) return std::move(insert).status();
        return spanner::Mutations{};
      },
      commit_options);
  if (!commit) throw std::move(commit).status();
}

C#

using Google.Cloud.Spanner.Data;
using System.Threading.Tasks;

public class TransactionTagAsyncSample
{
    public async Task<int> TransactionTagAsync(string projectId, string instanceId, string databaseId)
    {
        string connectionString = $"Data Source=projects/{projectId}/instances/{instanceId}/databases/{databaseId}";
        using var connection = new SpannerConnection(connectionString);
        await connection.OpenAsync();

        return await connection.RunWithRetriableTransactionAsync(async transaction =>
        {
            // Sets the transaction tag to "app=concert,env=dev".
            // This transaction tag will be applied to all the individual operations inside
            // the transaction.
            transaction.Tag = "app=concert,env=dev";

            // Sets the request tag to "app=concert,env=dev,action=update".
            // This request tag will only be set on this request.
            var updateCommand =
                connection.CreateDmlCommand("UPDATE Venues SET Capacity = DIV(Capacity, 4) WHERE OutdoorVenue = false");
            updateCommand.Tag = "app=concert,env=dev,action=update";
            updateCommand.Transaction = transaction;
            int rowsModified = await updateCommand.ExecuteNonQueryAsync();

            var insertCommand = connection.CreateDmlCommand(
                @"INSERT INTO Venues (VenueId, VenueName, Capacity, OutdoorVenue, LastUpdateTime)
                    VALUES (@venueId, @venueName, @capacity, @outdoorVenue, PENDING_COMMIT_TIMESTAMP())",
                new SpannerParameterCollection
                {
                    {"venueId", SpannerDbType.Int64, 81},
                    {"venueName", SpannerDbType.String, "Venue 81"},
                    {"capacity", SpannerDbType.Int64, 1440},
                    {"outdoorVenue", SpannerDbType.Bool, true}
                }
            );
            // Sets the request tag to "app=concert,env=dev,action=insert".
            // This request tag will only be set on this request.
            insertCommand.Tag = "app=concert,env=dev,action=insert";
            insertCommand.Transaction = transaction;
            rowsModified += await insertCommand.ExecuteNonQueryAsync();
            return rowsModified;
        });
    }
}

Go

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/spanner"
)

// readWriteTransactionWithTag executes the update and insert queries on venues table with appropriate transaction and requests tag
func readWriteTransactionWithTag(w io.Writer, db string) error {
	// db = `projects/<project>/instances/<instance-id>/database/<database-id>`
	ctx := context.Background()
	client, err := spanner.NewClient(ctx, db)
	if err != nil {
		return err
	}
	defer client.Close()

	_, err = client.ReadWriteTransactionWithOptions(ctx, func(ctx context.Context, txn *spanner.ReadWriteTransaction) error {
		stmt := spanner.Statement{
			SQL: `UPDATE Venues SET Capacity = CAST(Capacity/4 AS INT64) WHERE OutdoorVenue = false`,
		}
		_, err := txn.UpdateWithOptions(ctx, stmt, spanner.QueryOptions{RequestTag: "app=concert,env=dev,action=update"})
		if err != nil {
			return err
		}
		fmt.Fprint(w, "Venue capacities updated.")
		stmt = spanner.Statement{
			SQL: `INSERT INTO Venues (VenueId, VenueName, Capacity, OutdoorVenue, LastUpdateTime)
                   VALUES (@venueId, @venueName, @capacity, @outdoorVenue, PENDING_COMMIT_TIMESTAMP())`,
			Params: map[string]interface{}{
				"venueId":      81,
				"venueName":    "Venue 81",
				"capacity":     1440,
				"outdoorVenue": true,
			},
		}
		_, err = txn.UpdateWithOptions(ctx, stmt, spanner.QueryOptions{RequestTag: "app=concert,env=dev,action=insert"})
		if err != nil {
			return err
		}
		fmt.Fprint(w, "New venue inserted.")
		return nil
	}, spanner.TransactionOptions{TransactionTag: "app=concert,env=dev"})
	return err
}

Java

static void setTransactionTag(DatabaseClient databaseClient) {
  // Sets the transaction tag to "app=concert,env=dev".
  // This transaction tag will be applied to all the individual operations inside this
  // transaction.
  databaseClient
      .readWriteTransaction(Options.tag("app=concert,env=dev"))
      .run(transaction -> {
        // Sets the request tag to "app=concert,env=dev,action=update".
        // This request tag will only be set on this request.
        transaction.executeUpdate(
            Statement.of("UPDATE Venues"
                + " SET Capacity = CAST(Capacity/4 AS INT64)"
                + " WHERE OutdoorVenue = false"),
            Options.tag("app=concert,env=dev,action=update"));
        System.out.println("Venue capacities updated.");

        Statement insertStatement = Statement.newBuilder(
            "INSERT INTO Venues"
                + " (VenueId, VenueName, Capacity, OutdoorVenue, LastUpdateTime)"
                + " VALUES ("
                + " @venueId, @venueName, @capacity, @outdoorVenue, PENDING_COMMIT_TIMESTAMP()"
                + " )")
            .bind("venueId")
            .to(81)
            .bind("venueName")
            .to("Venue 81")
            .bind("capacity")
            .to(1440)
            .bind("outdoorVenue")
            .to(true)
            .build();

        // Sets the request tag to "app=concert,env=dev,action=insert".
        // This request tag will only be set on this request.
        transaction.executeUpdate(
            insertStatement,
            Options.tag("app=concert,env=dev,action=insert"));
        System.out.println("New venue inserted.");

        return null;
      });
}

Node.js

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = 'my-project-id';
// const instanceId = 'my-instance';
// const databaseId = 'my-database';

// Imports the Google Cloud client library
const {Spanner} = require('@google-cloud/spanner');

// Creates a client
const spanner = new Spanner({
  projectId: projectId,
});

async function transactionTag() {
  // Gets a reference to a Cloud Spanner instance and database.
  const instance = spanner.instance(instanceId);
  const database = instance.database(databaseId);

  // Run a transaction with a transaction tag that will automatically be
  // included with each request in the transaction.
  try {
    await database.runTransactionAsync(
      {requestOptions: {transactionTag: 'app=cart,env=dev'}},
      async tx => {
        // Set the request tag to "app=concert,env=dev,action=update".
        // This request tag will only be set on this request.
        await tx.runUpdate({
          sql: 'UPDATE Venues SET Capacity = DIV(Capacity, 4) WHERE OutdoorVenue = false',
          requestOptions: {requestTag: 'app=concert,env=dev,action=update'},
        });
        console.log('Updated capacity of all indoor venues to 1/4.');

        await tx.runUpdate({
          sql: `INSERT INTO Venues (VenueId, VenueName, Capacity, OutdoorVenue, LastUpdateTime)
                VALUES (@venueId, @venueName, @capacity, @outdoorVenue, PENDING_COMMIT_TIMESTAMP())`,
          params: {
            venueId: 81,
            venueName: 'Venue 81',
            capacity: 1440,
            outdoorVenue: true,
          },
          types: {
            venueId: {type: 'int64'},
            venueName: {type: 'string'},
            capacity: {type: 'int64'},
            outdoorVenue: {type: 'bool'},
          },
          requestOptions: {requestTag: 'app=concert,env=dev,action=update'},
        });
        console.log('Inserted new outdoor venue');

        await tx.commit();
      }
    );
  } catch (err) {
    console.error('ERROR:', err);
  } finally {
    await database.close();
  }
}
transactionTag();

PHP

use Google\Cloud\Spanner\SpannerClient;
use Google\Cloud\Spanner\Transaction;

/**
 * Executes a transaction with a transaction tag.
 * Example:
 * ```
 * spanner_set_transaction_tag($instanceId, $databaseId);
 * ```
 *
 * @param string $instanceId The Spanner instance ID.
 * @param string $databaseId The Spanner database ID.
 */
function set_transaction_tag(string $instanceId, string $databaseId): void
{
    $spanner = new SpannerClient();
    $instance = $spanner->instance($instanceId);
    $database = $instance->database($databaseId);

    $database->runTransaction(function (Transaction $t) {
        $t->executeUpdate(
            'UPDATE Venues SET Capacity = CAST(Capacity/4 AS INT64) WHERE OutdoorVenue = false',
            [
                'requestOptions' => ['requestTag' => 'app=concert,env=dev,action=update']
            ]
        );
        print('Venue capacities updated.' . PHP_EOL);
        $t->executeUpdate(
            'INSERT INTO Venues (VenueId, VenueName, Capacity, OutdoorVenue, LastUpdateTime) '
            . 'VALUES (@venueId, @venueName, @capacity, @outdoorVenue, PENDING_COMMIT_TIMESTAMP())',
            [
                'parameters' => [
                    'venueId' => 81,
                    'venueName' => 'Venue 81',
                    'capacity' => 1440,
                    'outdoorVenue' => true,
                ],
                'requestOptions' => ['requestTag' => 'app=concert,env=dev,action=insert']
            ]
        );
        print('New venue inserted.' . PHP_EOL);
        $t->commit();
    }, [
        'requestOptions' => ['transactionTag' => 'app=concert,env=dev']
    ]);
}

Python

# instance_id = "your-spanner-instance"
# database_id = "your-spanner-db-id"
spanner_client = spanner.Client()
instance = spanner_client.instance(instance_id)
database = instance.database(database_id)

def update_venues(transaction):
    # Sets the request tag to "app=concert,env=dev,action=update".
    #  This request tag will only be set on this request.
    transaction.execute_update(
        "UPDATE Venues SET Capacity = CAST(Capacity/4 AS INT64) WHERE OutdoorVenue = false",
        request_options={"request_tag": "app=concert,env=dev,action=update"},
    )
    print("Venue capacities updated.")

    # Sets the request tag to "app=concert,env=dev,action=insert".
    # This request tag will only be set on this request.
    transaction.execute_update(
        "INSERT INTO Venues (VenueId, VenueName, Capacity, OutdoorVenue, LastUpdateTime) "
        "VALUES (@venueId, @venueName, @capacity, @outdoorVenue, PENDING_COMMIT_TIMESTAMP())",
        params={
            "venueId": 81,
            "venueName": "Venue 81",
            "capacity": 1440,
            "outdoorVenue": True,
        },
        param_types={
            "venueId": param_types.INT64,
            "venueName": param_types.STRING,
            "capacity": param_types.INT64,
            "outdoorVenue": param_types.BOOL,
        },
        request_options={"request_tag": "app=concert,env=dev,action=insert"},
    )
    print("New venue inserted.")

database.run_in_transaction(update_venues, transaction_tag="app=concert,env=dev")

Rita

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client = spanner.client instance_id, database_id

client.transaction request_options: { tag: "app=cart,env=dev" } do |tx|
  tx.execute_update \
    "UPDATE Venues SET Capacity = CAST(Capacity/4 AS INT64) WHERE OutdoorVenue = false",
    request_options: { tag: "app=concert,env=dev,action=update" }

  puts "Venue capacities updated."

  tx.execute_update \
    "INSERT INTO Venues (VenueId, VenueName, Capacity, OutdoorVenue) " \
    "VALUES (@venue_id, @venue_name, @capacity, @outdoor_venue)",
    params: {
      venue_id: 81,
      venue_name: "Venue 81",
      capacity: 1440,
      outdoor_venue: true
    },
    request_options: { tag: "app=concert,env=dev,action=insert" }

  puts "New venue inserted."
end

Cómo ver las etiquetas de transacción en la tabla de estadísticas de transacciones

La siguiente consulta muestra las estadísticas de transacciones en intervalos de 10 minutos.

SELECT t.fprint,
       t.transaction_tag,
       t.read_columns,
       t.commit_attempt_count,
       t.avg_total_latency_seconds
FROM SPANNER_SYS.TXN_STATS_TOP_10MINUTE AS t
LIMIT 3;

Tomemos los siguientes datos como ejemplo de los resultados que obtenemos de nuestra consulta.

fprint	transaction_tag	read_columns	commit_attempt_count	avg_total_latency_seconds
40015598317	app=concert,env=dev	[Venues._exists, Venues.VenueId, Venues.VenueName, Lugares.Capacidad]	278802	0.3508
20524969030	app=product,service=payment	[Singers.SingerInfo]	129012	0.0142
77848338483	[string vacía]	[Singers.FirstName, Singers.LastName, Singers._exists]	5357	0.048

En esta tabla de resultados, podemos ver que, si asignaste un TRANSACTION_TAG a una transacción, se propaga en la tabla de estadísticas de transacciones. Si no hay una etiqueta de transacción asignada, se muestra como una string vacía.

Para las transacciones etiquetadas, las estadísticas se agregan por etiqueta de transacción (p.ej., la etiqueta de transacción app=concert,env=dev tiene una latencia promedio de 0.3508 segundos). Si no hay ninguna etiqueta asignada, las estadísticas se agregan por FPRINT (p.ej., 77848338483 en la tercera fila tiene una latencia promedio de 0.048 segundos).

Cómo ver las etiquetas de transacción en la tabla de estadísticas de bloqueo

La siguiente consulta muestra las estadísticas de bloqueo en intervalos de 10 minutos.

La función CAST() convierte el campo row_range_start_key BYTES en una STRING.

SELECT
   CAST(s.row_range_start_key AS STRING) AS row_range_start_key,
   s.lock_wait_seconds,
   s.sample_lock_requests
FROM SPANNER_SYS.LOCK_STATS_TOP_10MINUTE s
LIMIT 2;

Tomemos los siguientes datos como ejemplo de los resultados que obtenemos de nuestra consulta.

row_range_start_key	lock_wait_seconds	sample_lock_requests
Canciones (2,1,1)	0.61	LOCK_MODE: ReaderShared COLUMN: Singers.SingerInfo TRANSACTION_TAG: app=product,service=shipping LOCK_MODE: WriterShared COLUMN: Singers.SingerInfo TRANSACTION_TAG: app=product,service=payment
albums(2,1+)	0.48	LOCK_MODE: ReaderShared COLUMN: users._exists1 TRANSACTION_TAG: [empty string] LOCK_MODE: WriterShared COLUMN: users._exists TRANSACTION_TAG: [empty string]

En esta tabla de resultados, podemos ver que, si asignaste un TRANSACTION_TAG a una transacción, se propaga en la tabla de estadísticas de bloqueo. Si no hay una etiqueta de transacción asignada, se muestra como una cadena vacía.

Asignación entre los métodos de la API y la etiqueta de solicitud o transacción

Las etiquetas de solicitud y las etiquetas de transacción se aplican a métodos de API específicos según si el modo de transacción es una transacción de solo lectura o una transacción de lectura y escritura. Por lo general, las etiquetas de transacción se aplican a las transacciones de lectura y escritura, mientras que las etiquetas de solicitud se aplican a las transacciones de solo lectura. En la siguiente tabla, se muestra la asignación de los métodos de la API a los tipos de etiquetas aplicables.

Métodos de la API	Modos de transacción	Solicitar etiqueta	Etiqueta de transacción
Read, StreamingRead	Transacción de solo lectura	Sí	No
	Transacción de lectura o escritura	Sí	Sí
EjecutarSql, EjecutarStreamingSql^1	Transacción de solo lectura^1	Sí^1	No
	Transacción de lectura o escritura	Sí	Sí
ExecuteBatchDml	Transacción de lectura o escritura	Sí	Sí
BeginTransaction	Transacción de lectura o escritura	No	Sí
Confirmación	Transacción de lectura o escritura	No	Sí

¹ Para las consultas de flujos de cambios ejecutadas con el conector de DataflowIO de Spanner Beam de Apache Beam, REQUEST_TAG contiene un nombre de trabajo de Dataflow.

Nota: Cuando usas una biblioteca cliente, puedes establecer un TRANSACTION_TAG al comienzo de la llamada de transacción de lectura y escritura que se aplica a todas las operaciones individuales dentro de esa transacción.

Limitaciones

Cuando agregues etiquetas a tus lecturas, consultas y transacciones, ten en cuenta las siguientes limitaciones:

• La longitud de una cadena de etiqueta se limita a 50 caracteres. Las cadenas que superan este límite se truncan.
• Solo se permiten caracteres ASCII (32-126) en una etiqueta. Los caracteres Unicode arbitrarios se reemplazan por guiones bajos.
• Se quitan de la cadena cualquier carácter que comience con el guion bajo (_).
• Las etiquetas distinguen mayúsculas de minúsculas. Por ejemplo, si agregas la etiqueta de solicitud APP=cart,ENV=dev a un conjunto de consultas y app=cart,env=dev a otro conjunto de consultas, Spanner agrega estadísticas por separado para cada etiqueta.

• Es posible que falten etiquetas en las tablas de estadísticas en las siguientes circunstancias:

  • Si Spanner no puede almacenar estadísticas de todas las operaciones etiquetadas que se ejecutan durante el intervalo en tablas, el sistema prioriza las operaciones con los recursos de mayor consumo durante el intervalo especificado.

Nombre de las etiquetas

Cuando asignes etiquetas a las operaciones de la base de datos, es importante considerar qué información deseas transmitir en cada cadena de etiqueta. La convención o patrón que elijas hace que tus etiquetas sean más eficaces. Por ejemplo, una asignación de nombres adecuada a las etiquetas facilita la correlación de las estadísticas con el código de la aplicación.

Puedes elegir cualquier etiqueta que desees dentro de las limitaciones establecidas. Sin embargo, te recomendamos que construyas una cadena de etiqueta como un conjunto de pares clave-valor separados por comas.

Por ejemplo, supongamos que usas una base de datos de Spanner para un caso de uso de comercio electrónico. Es posible que desees incluir información sobre la aplicación, el entorno de desarrollo y la acción que realiza la consulta en la etiqueta de solicitud que asignarás a una consulta específica. Puedes asignar la cadena de etiqueta en el formato de par clave-valor como app=cart,env=dev,action=update.Esto significa que la consulta se llama desde la aplicación del carrito en el entorno de desarrollo y se usa para actualizar el carrito.

Supongamos que tienes otra consulta de una aplicación de búsqueda de catálogo y asignas la string de etiqueta como app=catalogsearch,env=dev,action=list. Si alguna de estas consultas aparece en la tabla de estadísticas de consultas como consultas de alta latencia, puedes identificar la fuente con facilidad mediante la etiqueta.

Estos son algunos ejemplos de cómo se puede usar un patrón de etiquetado para organizar tus estadísticas de operación. Estos ejemplos no son exhaustivos; también puedes combinarlos en tu cadena de etiqueta con un delimitador, como una coma.

Claves de etiquetas	Ejemplos de par etiqueta-valor	Descripción
Aplicación	app=cart app=frontend app=catalogsearch	Ayuda a identificar la aplicación que llama a la operación.
Entorno	env=prod env=dev env=test env=staging	Ayuda a identificar el entorno asociado con la operación.
Framework	framework=spring framework=django framework=jetty	Ayuda a identificar el framework asociado con la operación.
Acción	action=list action=retrieve action=update	Ayuda a identificar la acción que realizó la operación.
Servicio	service=payment service=shipping	Ayuda a identificar el microservicio que llama a la operación.

Observe lo siguiente:

• Cuando asignas una REQUEST_TAG, las estadísticas de varias consultas que tienen la misma cadena de etiqueta se agrupan en una sola fila en la tabla de estadísticas de consulta. Solo se muestra el texto de una de esas consultas en el campo TEXT.
• Cuando asignas un REQUEST_TAG, las estadísticas de varias lecturas que tienen la misma string de etiqueta se agrupan en una sola fila en la tabla de estadísticas de lectura. El conjunto de todas las columnas que se leen se agrega al campo READ_COLUMNS.
• Cuando asignas una TRANSACTION_TAG, las estadísticas de las transacciones que tienen la misma cadena de etiqueta se agrupan en una sola fila en la tabla de estadísticas de transacciones. El conjunto de todas las columnas que escriben las transacciones se agrega al campo WRITE_CONSTRUCTIVE_COLUMNS y el conjunto de todas las columnas que se leen se agrega al campo READ_COLUMNS.

Nota: Evita usar información de identificación personal (PII) y otros datos del usuario en una etiqueta. Las etiquetas no están diseñadas para contener información sensible.

Situaciones de solución de problemas con etiquetas

Encuentra la fuente de una transacción problemática

La siguiente consulta muestra los datos sin procesar de las transacciones principales en el período seleccionado.

SELECT
 fprint,
 transaction_tag,
 ROUND(avg_total_latency_seconds,4) as avg_total_latency_sec,
 ROUND(avg_commit_latency_seconds,4) as avg_commit_latency_sec,
 commit_attempt_count,
 commit_abort_count
FROM SPANNER_SYS.TXN_STATS_TOP_10MINUTE
WHERE interval_end = "2020-05-17T18:40:00"
ORDER BY avg_total_latency_seconds DESC;

En la tabla siguiente, se muestran datos de ejemplo de nuestra consulta, en los que tenemos tres aplicaciones: cart, product y frontend, que pertenecen o consultan la misma base de datos.

Una vez que identifiques las transacciones con latencia alta, puedes usar las etiquetas asociadas para identificar la parte relevante del código de tu aplicación y seguir solucionando el problema con las estadísticas de transacciones.

fprint	transaction_tag	avg_total_latency_sec	avg_commit_latency_sec	commit_attempt_count	commit_abort_count
7129109266372596045	app=cart,service=order	0.3508	0.0139	278802	142205
9353100217060788102	app=cart,service=redis	0.1633	0.0142	129012	27177
9353100217060788102	app=product,service=payment	0.1423	0.0133	5357	636
898069986622520747	app=product,service=shipping	0.0159	0.0118	4269	1
9521689070912159706	app=frontend,service=ads	0.0093	0.0045	164	0
11079878968512225881	[string vacía]	0.031	0.015	14	0

Del mismo modo, se puede usar la etiqueta de solicitud para encontrar la fuente de una consulta problemática en la tabla estadísticas de consultas y la fuente de lectura problemática en la tabla lectura de estadísticas.

Encuentra la latencia y otras estadísticas de las transacciones de una aplicación o un microservicio en particular

Si usaste el nombre de la aplicación o del microservicio en la string de etiqueta, ayuda a filtrar la tabla de estadísticas de transacciones por etiquetas que contengan ese nombre de aplicación o de microservicio.

Supongamos que agregaste transacciones nuevas a la app de pagos y deseas consultar las latencias y otras estadísticas de esas transacciones nuevas. Si usaste el nombre de la aplicación de pagos dentro de la etiqueta, puedes filtrar la tabla de estadísticas de transacciones solo para las etiquetas que contengan app=payment.

La siguiente consulta muestra las estadísticas de transacción para la app de pagos en intervalos de 10 minutos.

SELECT
  transaction_tag,
  avg_total_latency_sec,
  avg_commit_latency_sec,
  commit_attempt_count,
  commit_abort_count
FROM SPANNER_SYS.TXN_STATS_TOP_10MINUTE
WHERE STARTS_WITH(transaction_tag, "app=payment")
LIMIT 3;

Este es un resultado de ejemplo:

transaction_tag	avg_total_latency_sec	avg_commit_latency_sec	commit_attempt_count	commit_abort_count
app=payment,action=update	0.3508	0.0139	278802	142205
app=payment,action=transfer	0.1633	0.0142	129012	27177
app=payment, action=retrieve	0.1423	0.0133	5357	636

Del mismo modo, puedes encontrar consultas o lecturas de una aplicación específica en las estadísticas de consultas o en la tabla de estadísticas de lectura con etiquetas de solicitud.

Cómo descubrir las transacciones involucradas en el conflicto de bloqueo

Para descubrir qué transacciones y claves de fila experimentaron los altos tiempos de espera de bloqueo, consultamos la tabla LOCK_STAT_TOP_10MINUTE, que enumera las claves de fila, las columnas y las transacciones correspondientes que participan en el conflicto de bloqueo.

SELECT CAST(s.row_range_start_key AS STRING) AS row_range_start_key,
       t.total_lock_wait_seconds,
       s.lock_wait_seconds,
       s.lock_wait_seconds/t.total_lock_wait_seconds frac_of_total,
       s.sample_lock_requests
FROM spanner_sys.lock_stats_total_10minute t, spanner_sys.lock_stats_top_10minute s
WHERE
  t.interval_end = "2020-05-17T18:40:00" and s.interval_end = t.interval_end;

Aquí hay un resultado de ejemplo de nuestra consulta:

row_range_start_key	total_lock_wait_seconds	lock_wait_seconds	frac_of_total	sample_lock_requests
Singers(32)	2.37	1.76	1	LOCK_MODE: WriterShared COLUMN: Singers.SingerInfo TRANSACTION_TAG: app=cart,service=order LOCK_MODE: ReaderShared COLUMN: Singers.SingerInfo TRANSACTION_TAG: app=cart,service=redis

En esta tabla de resultados, podemos ver que el conflicto ocurrió en la tabla Singers en la clave SingerId=32. Singers.SingerInfo es la columna en la que se produjo el conflicto de bloqueo entre ReaderShared y WriterShared. También puedes identificar las transacciones correspondientes (app=cart,service=order y app=cart,service=redis) que experimentan el conflicto.

Una vez que se identifican las transacciones que causan los conflictos de bloqueo, puedes enfocarte en estas transacciones. Para ello, usa las estadísticas de transacciones y obtén una idea más clara de lo que hacen las transacciones y si puedes evitar conflictos o reducir el tiempo durante el cual se retienen los bloqueos. Si deseas obtener más información, consulta Prácticas recomendadas para reducir la contención de bloqueo.

¿Qué sigue?

• Obtén más información sobre otras herramientas de introspección.
• Obtén información sobre otros datos que Spanner almacena para cada base de datos en las tablas de esquema de información de la base de datos.
• Obtén más información sobre las prácticas recomendadas de SQL para Spanner.
• Obtén más información sobre cómo investigar el alto uso de CPU.