Soluciona problemas 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 información sobre tus consultas, lecturas y transacciones. Para correlacionar las estadísticas con el código de la aplicación y mejorar la solución de problemas, puedes agregar una etiqueta (una cadena de formato libre) a las operaciones de lectura, consulta y transacción de Spanner en el código de la aplicación. Estas etiquetas se propagan en las tablas de estadísticas, lo que te ayuda a correlacionar y buscar en función de las etiquetas.

Spanner admite dos tipos de etiquetas: etiquetas de solicitud y etiquetas de transacción. Como sus nombres lo sugieren, puedes agregar etiquetas de transacción a las transacciones y etiquetas de solicitud a las APIs de lectura y consultas individuales. Puedes establecer una etiqueta de transacción en el alcance de la transacción y establecer etiquetas de solicitud individuales para cada solicitud a la API aplicable dentro de la transacción. Las etiquetas de solicitud y las etiquetas de transacción que se configuran 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 que se completan en la tabla de estadísticas
Estadísticas de las principales N consultas Etiquetas de solicitud
Estadísticas de lectura de TopN Etiquetas de solicitud
Estadísticas de transacciones de TopN Etiquetas de transacción
TopN Lock Statistics Etiquetas de transacción

Etiquetas de solicitud

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

Cuándo usar etiquetas de solicitud

A continuación, se incluyen algunos de los casos en los que es beneficioso usar etiquetas de solicitud.

  • Cómo encontrar la fuente de una lectura o consulta problemática: Spanner recopila estadísticas de lecturas y consultas en tablas de estadísticas integradas. Cuando encuentres las consultas lentas o las lecturas con un alto consumo de CPU en la tabla de estadísticas, si ya les asignaste etiquetas, podrás identificar la fuente (aplicación o microservicio) que llama a estas operaciones según la información de la etiqueta.
  • Identifica lecturas o consultas en las 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.
  • Determinar 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, compararlo y generar informes sobre él en un conjunto de lecturas o consultas similares. Por ejemplo, si varias consultas acceden a una tabla o a un conjunto de tablas con el mismo patrón de acceso, puedes considerar agregar la misma etiqueta a todas esas consultas para hacer un seguimiento conjunto.

Cómo asignar etiquetas de solicitud

En el siguiente ejemplo, se muestra cómo establecer etiquetas de solicitud con 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))

Ruby

# 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 solicitudes en la tabla de estadísticas

La siguiente consulta devuelve las estadísticas de las consultas 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;

Los siguientes datos son un ejemplo de los resultados que devuelve la 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
select * from orders; 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 búsqueda, se completará en la tabla de estadísticas. Si no hay ninguna etiqueta de solicitud asignada, se muestra como una cadena vacía.

En el caso de 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 se asigna ninguna etiqueta, las estadísticas se agregan por búsqueda (p.ej., la búsqueda en 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 las 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

A continuación, se incluyen algunos de los casos en los que es beneficioso usar etiquetas de transacción.

  • Cómo encontrar la fuente de una transacción problemática: Spanner recopila estadísticas de las 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, podrás identificar la fuente (aplicación o microservicio) que llama a estas transacciones según la información de la etiqueta.
  • Identifica transacciones en las tablas de estadísticas: Asignar etiquetas de transacciones ayuda a filtrar las filas de la tabla de estadísticas de transacciones según las etiquetas que te interesan. Sin etiquetas de transacción, descubrir qué operaciones representa una estadística puede ser un proceso engorroso. Por ejemplo, para las estadísticas de transacciones, deberás examinar las tablas y las columnas involucradas para identificar la transacción sin etiquetar.
  • Cómo determinar 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 transacciones para hacer un seguimiento del rendimiento de un conjunto de transacciones similares, compararlo y generar informes al respecto.
  • Cómo encontrar las transacciones que acceden a las columnas involucradas en el conflicto de bloqueo: Las etiquetas de transacción pueden ayudar a identificar las transacciones individuales que causan conflictos de bloqueo en las tablas de estadísticas de bloqueo.
  • Transmisión de datos de cambios del usuario fuera de Spanner con 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 según las etiquetas.

Cómo asignar etiquetas de transacción

En el siguiente ejemplo, se muestra cómo establecer etiquetas de transacción con las bibliotecas cliente de Spanner. Cuando usas una biblioteca cliente, puedes establecer 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.TransactionOptions.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")

Ruby

# 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 devuelve 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;

Los siguientes datos son un ejemplo de los resultados que devuelve la consulta.

fprint transaction_tag read_columns commit_attempt_count avg_total_latency_seconds
40015598317 app=concert,env=dev [Venues._exists,
Venues.VenueId,
Venues.VenueName,
Venues.Capacity]
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 completará en la tabla de estadísticas de transacciones. Si no hay ninguna etiqueta de transacción asignada, se muestra como una cadena vacía.

En el caso de las transacciones etiquetadas, las estadísticas se agregan por etiqueta de transacción (p.ej., la etiqueta de transacción app=concert,env=dev a tiene una latencia promedio de 0.3508 segundos). Si no se asigna ninguna etiqueta, 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 transacciones en la tabla de estadísticas de bloqueo

La siguiente consulta devuelve 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;

Los siguientes datos son un ejemplo de los resultados que devuelve la 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 completará en la tabla de estadísticas de bloqueo. Si no hay ninguna etiqueta de transacción asignada, se muestra como una cadena vacía.

Asigna etiquetas automáticamente

Las bibliotecas cliente de Spanner admiten el etiquetado automático de la pila de llamadas. Cuando el etiquetado automático está habilitado, la biblioteca cliente inspecciona la pila de llamadas de ejecución de tu aplicación para determinar qué clase y método iniciaron la solicitud de la base de datos. Genera automáticamente una etiqueta basada en estos nombres (por ejemplo, OrderDao.placeOrder en Java o db__OrderDao__PlaceOrder en Go) y completa el request_tag o el transaction_tag.

El etiquetado automático es compatible con las siguientes bibliotecas cliente:

  • Java en la versión 6.118.0 y posteriores
  • Go en la versión 1.92.0 y posteriores

Consideraciones sobre el etiquetado automático

Ten en cuenta lo siguiente antes de usar el etiquetado automático:

  • Sobrecarga de CPU y latencia: La inspección de las pilas de llamadas del tiempo de ejecución con reflexión o el recorrido del llamador del tiempo de ejecución en cada solicitud y transacción introduce una sobrecarga de CPU y latencia. Antes de habilitar forzosamente el etiquetado automático de forma global en entornos de producción con un QPS alto, evalúa el impacto en el rendimiento de tus servicios.
  • Diferencias con el etiquetado de par clave-valor: Las etiquetas generadas automáticamente (como OrderDao.placeOrder) identifican símbolos de origen del código en lugar de metadatos estructurados de par clave-valor (como app=cart,env=dev). Si tus consultas de supervisión filtran tablas de estadísticas con prefijos de clave como STARTS_WITH(request_tag, "app="), las operaciones etiquetadas automáticamente no coincidirán con esos filtros.
  • Cardinalidad de la etiqueta: Los nombres de métodos dinámicos o muy sobrecargados pueden aumentar la cardinalidad de la etiqueta en las tablas de estadísticas. Si la cantidad de etiquetas únicas supera la capacidad de seguimiento de Spanner durante un intervalo, Spanner prioriza las operaciones de seguimiento con el mayor consumo de recursos.
  • Divulgación de información: Debido a que las etiquetas se almacenan en texto sin formato en las tablas de estadísticas de SPANNER_SYS, los nombres internos de las clases y los métodos son visibles para cualquier persona que tenga acceso a las estadísticas de la base de datos de consultas. Evita usar terminología comercial sensible en los nombres de métodos o clases si el acceso de supervisión se comparte entre límites.

Habilita e inhabilita el etiquetado automático

Puedes configurar el etiquetado automático en el código o establecer la configuración de forma global con variables de entorno.

Reglas de prioridad de configuración

Si asignas manualmente un request_tag o un transaction_tag en un compilador de solicitudes o transacciones, esa etiqueta siempre tendrá prioridad sobre cualquier etiqueta de pila de llamadas generada automáticamente. Si no hay una etiqueta manual, la configuración del etiquetado automático sigue estas reglas de prioridad:

  1. Anulación de la inhabilitación forzada: Si se establece SPANNER_DISABLE_AUTO_TAGGING=true, el etiquetado automático se inhabilita por completo de forma global, lo que anula las configuraciones programáticas.
  2. Anulación de la habilitación forzada: Si se establece SPANNER_ENABLE_AUTO_TAGGING=true, el etiquetado automático se habilita de forma global y anula las configuraciones programáticas.
  3. Configuración programática: Si no se configuran variables de entorno de anulación, la biblioteca usa la configuración programática establecida en SpannerOptions (Java) o ClientConfig (Go).
  4. Comportamiento predeterminado: Si no configuras el etiquetado automático, este se inhabilita de forma predeterminada.

Anulaciones globales

Para forzar la habilitación o inhabilitación del etiquetado automático a nivel global sin modificar el código de la aplicación, configura las variables de entorno en tu entorno de ejecución:

# Force-enable globally
export SPANNER_ENABLE_AUTO_TAGGING=true

# Force-disable globally (overrides code configuration)
export SPANNER_DISABLE_AUTO_TAGGING=true

Configuración programática

En los siguientes ejemplos, se muestra cómo habilitar el etiquetado automático de la pila de llamadas con las bibliotecas cliente de Spanner.

Go

package main

import (
    "context"
    "cloud.google.com/go/spanner"
)

func main() {
    ctx := context.Background()
    config := spanner.ClientConfig{
        // Enable call-stack autotagging
        EnableAutoTagging: true,
        // Optional: Specify target application package prefixes
        AutoTaggingPackages: []string{"github.com/mycompany/orderingservice"},
        // Optional: Set maximum stack depth to inspect (default is 50)
        AutoTaggingTracerLimit: 50,
    }
    client, err := spanner.NewClientWithConfig(ctx, "projects/p/instances/i/databases/d", config)
    if err != nil {
        panic(err)
    }
    defer client.Close()
}

Java

import com.google.cloud.spanner.Spanner;
import com.google.cloud.spanner.SpannerOptions;
import java.util.Arrays;

SpannerOptions options = SpannerOptions.newBuilder()
    // Enable call-stack autotagging
    .enableAutoTagging()
    // Optional: Specify target application package prefixes
    .setAutoTaggingPackages(Arrays.asList("com.mycompany.orderingservice."))
    // Optional: Set maximum stack depth to inspect (default is 50)
    .setAutoTaggingTracerLimit(100)
    .build();
Spanner spanner = options.getService();

Asignación entre los métodos de la API y las etiquetas de solicitud y 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 de solo lectura o de lectura y escritura. En 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 Etiqueta de solicitud Etiqueta de transacción
Read,
StreamingRead
Transacción de solo lectura Sí No
Transacción de lectura o escritura Sí Sí
ExecuteSql,
ExecuteStreamingSql1
Transacción de solo lectura1 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í

1 Para las consultas de flujos de cambios que se ejecutan con el conector de Dataflow de SpannerIO de Apache Beam, el objeto REQUEST_TAG contiene un nombre de trabajo de Dataflow.

Limitaciones

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

  • La longitud de una cadena de etiquetas se limita a 50 caracteres. Las cadenas que superen este límite se truncarán.
  • En una etiqueta, solo se permiten caracteres ASCII (32 a 126). Los caracteres Unicode arbitrarios se reemplazan por guiones bajos.
  • Se quitan todos los caracteres de guion bajo (_) iniciales de la cadena.
  • Las etiquetas distinguen mayúsculas de minúsculas. Por ejemplo, si agregas la etiqueta de solicitud APP=cart,ENV=dev a un conjunto de búsquedas y agregas app=cart,env=dev a otro conjunto de búsquedas, 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 las tablas, el sistema prioriza las operaciones con los recursos de mayor consumo durante el intervalo especificado.

Nombres de las etiquetas

Cuando asignes etiquetas a tus operaciones de bases de datos, es importante que tengas en cuenta qué información deseas transmitir en cada cadena de etiquetas. La convención o el patrón que elijas harán que tus etiquetas sean más eficaces. Por ejemplo, el uso de nombres adecuados para las etiquetas facilita la correlación de las estadísticas con el código de la aplicación.

Puedes elegir cualquier etiqueta dentro de las limitaciones establecidas. Sin embargo, recomendamos construir una cadena de etiquetas 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 desee 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 va a asignar a una consulta en particular. Puedes considerar asignar la cadena de etiquetas en el formato 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 utiliza para actualizar el carrito.

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

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

Claves de etiquetas Ejemplos de pares clave-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 a la operación.
Framework framework=spring
framework=django
framework=jetty
Ayuda a identificar el framework asociado a la operación.
Acción action=list
action=retrieve
action=update
Ayuda a identificar la acción que realiza 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 búsquedas que tienen la misma cadena de etiquetas se agrupan en una sola fila en la tabla de estadísticas de búsqueda. Solo el texto de una de esas búsquedas se muestra en el campo TEXT.
  • Cuando asignas un REQUEST_TAG, las estadísticas de varias lecturas que tienen la misma cadena de etiquetas 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 un TRANSACTION_TAG, las estadísticas de las transacciones que tienen la misma cadena de etiquetas 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.

Situaciones de solución de problemas con etiquetas

En las siguientes situaciones, se describe cómo usar etiquetas para solucionar problemas de rendimiento.

Cómo encontrar el origen 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 que experimentan una latencia alta, puedes usar las etiquetas asociadas para identificar la parte pertinente del código de la aplicación y solucionar problemas 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.

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

Si ha utilizado el nombre de la aplicación o del microservicio en la cadena de etiquetas, esto 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 pago y deseas consultar las latencias y otras estadísticas de esas transacciones nuevas. Si ha utilizado el nombre de la aplicación de pago dentro de la etiqueta, puede filtrar la tabla de estadísticas de transacciones para que solo muestre aquellas etiquetas que contengan app=payment.

La siguiente consulta muestra las estadísticas de transacciones de 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 ejemplo de resultado:

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 tablas estadísticas de consultas o estadísticas de lecturas con etiquetas de solicitud.

Descubre las transacciones involucradas en el conflicto de bloqueo

Para averiguar qué transacciones y claves de fila experimentaron tiempos de espera de bloqueo altos, consultamos la tabla LOCK_STAT_TOP_10MINUTE, que enumera las claves de fila, las columnas y las transacciones correspondientes que están involucradas 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í tenéis un ejemplo del resultado 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 puede identificar las transacciones correspondientes (app=cart,service=order y app=cart,service=redis) que están experimentando el conflicto.

Una vez que se identifican las transacciones que causan los conflictos de bloqueo, puedes concentrarte en ellas con Estadísticas de transacciones para comprender mejor qué hacen las transacciones y si puedes evitar un conflicto o reducir el tiempo durante el que se mantienen los bloqueos. Si quieres obtener más información, consulta Prácticas recomendadas para reducir la contención de bloqueos.

¿Qué sigue?