logging

Documentation

Overview

Package logging contains shared environment variable and log functionality.

Index

• Constants
• func DataSourceContext(ctx context.Context, dataSource string) context.Context
• func InitContext(ctx context.Context, sdkOpts tfsdklog.Options, providerOpts tflog.Options) context.Context
• func ProtoSubsystemContext(ctx context.Context, sdkOpts tfsdklog.Options) context.Context
• func ProtocolData(ctx context.Context, dataDir string, rpc string, message string, field string, ...)
• func ProtocolError(ctx context.Context, msg string, additionalFields ...map[string]interface{})
• func ProtocolPrivateData(ctx context.Context, dataDir string, rpc string, message string, field string, ...)
• func ProtocolSetField(ctx context.Context, key string, value any) context.Context
• func ProtocolTrace(ctx context.Context, msg string, additionalFields ...map[string]interface{})
• func ProtocolVersionContext(ctx context.Context, protocolVersion string) context.Context
• func ProtocolWarn(ctx context.Context, msg string, additionalFields ...map[string]interface{})
• func ProviderAddressContext(ctx context.Context, providerAddress string) context.Context
• func ProviderLoggerName(providerAddress string) string
• func RequestIdContext(ctx context.Context) context.Context
• func ResourceContext(ctx context.Context, resource string) context.Context
• func RpcContext(ctx context.Context, rpc string) context.Context

Constants

const (
	// EnvTfLogProvider is the prefix of the environment variable that sets the
	// logging level of the root provider logger for the provider being served.
	// The suffix is an underscore and the parsed provider name. For example,
	// registry.terraform.io/hashicorp/example becomes TF_LOG_PROVIDER_EXAMPLE.
	EnvTfLogProvider = "TF_LOG_PROVIDER"

	// EnvTfLogSdk is an environment variable that sets the root logging level
	// of SDK loggers.
	EnvTfLogSdk = "TF_LOG_SDK"

	// EnvTfLogSdkProto is an environment variable that sets the logging level
	// of SDK protocol loggers. Infers root SDK logging level, if unset.
	EnvTfLogSdkProto = "TF_LOG_SDK_PROTO"

	// EnvTfLogSdkProtoDataDir is an environment variable that sets the
	// directory to write raw protocol data files for debugging purposes.
	EnvTfLogSdkProtoDataDir = "TF_LOG_SDK_PROTO_DATA_DIR"
)

Environment variables.

const (
	// Attribute of the diagnostic being logged.
	KeyDiagnosticAttribute = "diagnostic_attribute"

	// Number of the error diagnostics.
	KeyDiagnosticErrorCount = "diagnostic_error_count"

	// Severity of the diagnostic being logged.
	KeyDiagnosticSeverity = "diagnostic_severity"

	// Detail of the diagnostic being logged.
	KeyDiagnosticDetail = "diagnostic_detail"

	// Summary of the diagnostic being logged.
	KeyDiagnosticSummary = "diagnostic_summary"

	// Number of the warning diagnostics.
	KeyDiagnosticWarningCount = "diagnostic_warning_count"

	// Underlying error string
	KeyError = "error"

	// Argument position of the function error.
	KeyFunctionErrorArgument = "function_error_argument"

	// Boolean indicating presence of function error
	KeyFunctionErrorExists = "function_error_exists"

	// Message of the function error.
	KeyFunctionErrorText = "function_error_text"

	// Duration in milliseconds for the RPC request
	KeyRequestDurationMs = "tf_req_duration_ms"

	// A unique ID for the RPC request
	KeyRequestID = "tf_req_id"

	// The full address of the provider, such as
	// registry.terraform.io/hashicorp/random
	KeyProviderAddress = "tf_provider_addr"

	// The RPC being run, such as "ApplyResourceChange"
	KeyRPC = "tf_rpc"

	// The type of resource being operated on, such as "random_pet"
	KeyResourceType = "tf_resource_type"

	// The type of data source being operated on, such as "archive_file"
	KeyDataSourceType = "tf_data_source_type"

	// Path to protocol data file, such as "/tmp/example.json"
	KeyProtocolDataFile = "tf_proto_data_file"

	// The protocol version being used, as a string, such as "6"
	KeyProtocolVersion = "tf_proto_version"

	// Whether the GetProviderSchemaOptional server capability is enabled
	KeyServerCapabilityGetProviderSchemaOptional = "tf_server_capability_get_provider_schema_optional"

	// Whether the PlanDestroy server capability is enabled
	KeyServerCapabilityPlanDestroy = "tf_server_capability_plan_destroy"
)

Global logging keys attached to all requests.

Practitioners or tooling reading logs may be depending on these keys, so be conscious of that when changing them.

const (
	// SubsystemProto is the tfsdklog subsystem name for protocol logging.
	SubsystemProto = "proto"
)

Functions

func DataSourceContext

func DataSourceContext(ctx context.Context, dataSource string) context.Context

DataSourceContext injects the data source type into logger contexts.

func InitContext

func InitContext(ctx context.Context, sdkOpts tfsdklog.Options, providerOpts tflog.Options) context.Context

InitContext creates SDK and provider logger contexts.

func ProtoSubsystemContext

func ProtoSubsystemContext(ctx context.Context, sdkOpts tfsdklog.Options) context.Context

ProtoSubsystemContext adds the proto subsystem to the SDK logger context.

func ProtocolData

func ProtocolData(ctx context.Context, dataDir string, rpc string, message string, field string, data interface{})

ProtocolData emits raw protocol data to a file, if given a directory.

The directory must exist and be writable, prior to invoking this function.

File names are in the format: {TIME}_{RPC}_{MESSAGE}_{FIELD}.{EXT}

func ProtocolError

func ProtocolError(ctx context.Context, msg string, additionalFields ...map[string]interface{})

ProtocolError emits a protocol subsystem log at ERROR level.

func ProtocolPrivateData

func ProtocolPrivateData(ctx context.Context, dataDir string, rpc string, message string, field string, data []byte)

ProtocolPrivateData emits raw protocol private data to a file, if given a directory. This data is "private" in the sense that it is provider-owned, rather than something managed by Terraform.

The directory must exist and be writable, prior to invoking this function.

File names are in the format: {TIME}_{RPC}_{MESSAGE}_{FIELD}(.empty)

func ProtocolSetField

func ProtocolSetField(ctx context.Context, key string, value any) context.Context

ProtocolSetField returns a context with the additional protocol subsystem field set.

func ProtocolTrace

func ProtocolTrace(ctx context.Context, msg string, additionalFields ...map[string]interface{})

ProtocolTrace emits a protocol subsystem log at TRACE level.

func ProtocolVersionContext

func ProtocolVersionContext(ctx context.Context, protocolVersion string) context.Context

ProtocolVersionContext injects the protocol version into logger contexts.

func ProtocolWarn

func ProtocolWarn(ctx context.Context, msg string, additionalFields ...map[string]interface{})

ProtocolWarn emits a protocol subsystem log at WARN level.

func ProviderAddressContext

func ProviderAddressContext(ctx context.Context, providerAddress string) context.Context

ProviderAddressContext injects the provider address into logger contexts.

func ProviderLoggerName

func ProviderLoggerName(providerAddress string) string

func RequestIdContext

func RequestIdContext(ctx context.Context) context.Context

RequestIdContext injects a unique request ID into logger contexts.

func ResourceContext

func ResourceContext(ctx context.Context, resource string) context.Context

ResourceContext injects the resource type into logger contexts.

func RpcContext

func RpcContext(ctx context.Context, rpc string) context.Context

RpcContext injects the RPC name into logger contexts.