Package com.linecorp.armeria.common.logging

Interface RequestOnlyLog

All Superinterfaces:

RequestLogAccess

All Known Subinterfaces:

RequestLog

public interface RequestOnlyLog
extends RequestLogAccess

A set of informational properties for request-side only, collected while consuming a Request.

See Also:

• RequestLogAccess.isRequestComplete()
• RequestLogAccess.whenRequestComplete()
• RequestLogAccess.ensureRequestComplete()

Method Summary

Modifier and Type	Method	Description
@Nullable String	authenticatedUser()	Returns the authenticated user which is used to print %u format of an access log.
@Nullable io.netty.channel.Channel	channel()	Returns the Netty Channel which handled the Request.
@Nullable ClientConnectionTimings	connectionTimings()	Returns the ClientConnectionTimings of the Request.
String	fullName()	Returns the human-readable full name, which is the concatenation of serviceName() and name() using '/', of the Request.
String	name()	Returns the human-readable simple name of the Request, such as: gRPC - A capitalized method name defined in io.grpc.MethodDescriptor (e.g, GetItems) Thrift and annotated service - a method name (e.g, getItems) HttpService - an HTTP method name This property is often used as a meter tag or distributed trace's span name.
@Nullable Object	rawRequestContent()	Returns the low-level content object of the Request, which is specific to the SerializationFormat.
@Nullable Throwable	requestCause()	Returns the cause of request processing failure.
@Nullable Object	requestContent()	Returns the high-level content object of the Request, which is specific to the SerializationFormat.
@Nullable String	requestContentPreview()	Returns the preview of request content of the Request.
default long	requestDurationNanos()	Returns the duration that was taken to consume or produce the request completely, in nanoseconds.
long	requestEndTimeNanos()	Returns the time when the processing of the request finished, in nanoseconds.
@Nullable Long	requestFirstBytesTransferredTimeNanos()	Returns the time when the first bytes of the request headers were transferred over the wire.
RequestHeaders	requestHeaders()	Returns the RequestHeaders.
long	requestLength()	Returns the length of the request content.
long	requestStartTimeMicros()	Returns the time when the processing of the request started, in microseconds since the epoch.
long	requestStartTimeMillis()	Returns the time when the processing of the request started, in milliseconds since the epoch.
long	requestStartTimeNanos()	Returns the time when the processing of the request started, in nanoseconds.
HttpHeaders	requestTrailers()	Returns the HTTP trailers of the Request.
Scheme	scheme()	Returns the Scheme of the Request.
SerializationFormat	serializationFormat()	Returns the SerializationFormat of the Request.
@Nullable String	serviceName()	Returns the human-readable name of the service that served the Request, such as: gRPC - a service name (e.g, com.foo.GrpcService) Thrift - a service type (e.g, com.foo.ThriftService$AsyncIface or com.foo.ThriftService$Iface) HttpService and annotated service - an innermost class name This property is often used as a meter tag or distributed trace's span name.
SessionProtocol	sessionProtocol()	Returns the SessionProtocol of the Request.
@Nullable SSLSession	sslSession()	Returns the SSLSession of the connection which handled the Request.
default String	toStringRequestOnly()	Deprecated. Use LogFormatter.formatRequest(RequestOnlyLog) instead.
default String	toStringRequestOnly(BiFunction<? super RequestContext,? super HttpHeaders,? extends @Nullable Object> headersSanitizer, BiFunction<? super RequestContext,Object,? extends @Nullable Object> contentSanitizer)	Deprecated. Use LogFormatter.formatRequest(RequestOnlyLog) instead.
default String	toStringRequestOnly(BiFunction<? super RequestContext,? super RequestHeaders,? extends @Nullable Object> headersSanitizer, BiFunction<? super RequestContext,Object,? extends @Nullable Object> contentSanitizer, BiFunction<? super RequestContext,? super HttpHeaders,? extends @Nullable Object> trailersSanitizer)	Deprecated. Use LogFormatter.formatRequest(RequestOnlyLog) instead.

Methods inherited from interface com.linecorp.armeria.common.logging.RequestLogAccess

availabilityStamp, children, context, ensureAvailable, ensureAvailable, ensureAvailable, ensureComplete, ensureRequestComplete, getIfAvailable, getIfAvailable, isAvailable, isAvailable, isAvailable, isComplete, isRequestComplete, parent, partial, whenAvailable, whenAvailable, whenAvailable, whenComplete, whenRequestComplete

Method Details

requestStartTimeMicros

long requestStartTimeMicros()

Returns the time when the processing of the request started, in microseconds since the epoch.

Throws:

RequestLogAvailabilityException - if the property is not available yet.

See Also:

• RequestLogProperty.REQUEST_START_TIME

requestStartTimeMillis

long requestStartTimeMillis()

Returns the time when the processing of the request started, in milliseconds since the epoch.

Throws:

RequestLogAvailabilityException - if the property is not available yet.

See Also:

• RequestLogProperty.REQUEST_START_TIME

requestStartTimeNanos

long requestStartTimeNanos()

Returns the time when the processing of the request started, in nanoseconds. This value can only be used to measure elapsed time and is not related to any other notion of system or wall-clock time.

Throws:

RequestLogAvailabilityException - if the property is not available yet.

See Also:

• RequestLogProperty.REQUEST_START_TIME

requestFirstBytesTransferredTimeNanos

@Nullable
@Nullable Long requestFirstBytesTransferredTimeNanos()

Returns the time when the first bytes of the request headers were transferred over the wire. For a client, this is the time the client sent the data, while for a server it is the time the server received them. This value can only be used to measure elapsed time and is not related to any other notion of system or wall-clock time.

Returns:

the transfer time, or null if nothing was transferred.

Throws:

RequestLogAvailabilityException - if the property is not available yet.

See Also:

• RequestLogProperty.REQUEST_FIRST_BYTES_TRANSFERRED_TIME

requestEndTimeNanos

long requestEndTimeNanos()

Returns the time when the processing of the request finished, in nanoseconds. This value can only be used to measure elapsed time and is not related to any other notion of system or wall-clock time.

Throws:

RequestLogAvailabilityException - if the property is not available yet.

See Also:

• RequestLogProperty.REQUEST_END_TIME

requestDurationNanos

default long requestDurationNanos()

Returns the duration that was taken to consume or produce the request completely, in nanoseconds.

Throws:

RequestLogAvailabilityException - if the property is not available yet.

See Also:

• RequestLogProperty.REQUEST_END_TIME

requestLength

long requestLength()

Returns the length of the request content.

Throws:

RequestLogAvailabilityException - if the property is not available yet.

See Also:

• RequestLogProperty.REQUEST_LENGTH

requestCause

@Nullable
@Nullable Throwable requestCause()

Returns the cause of request processing failure.

Returns:

the cause, or null if the request was processed completely.

Throws:

RequestLogAvailabilityException - if the property is not available yet.

See Also:

• RequestLogProperty.REQUEST_CAUSE

channel

@Nullable
@Nullable io.netty.channel.Channel channel()

Returns the Netty Channel which handled the Request.

Returns:

the Netty Channel, or null if the Request has failed even before a connection is established.

Throws:

RequestLogAvailabilityException - if the property is not available yet.

See Also:

• RequestLogProperty.SESSION

sslSession

@Nullable
@Nullable SSLSession sslSession()

Returns the SSLSession of the connection which handled the Request.

Returns:

the SSLSession, or null if the Request has failed even before a TLS connection is established or the connection does not use TLS.

Throws:

RequestLogAvailabilityException - if the property is not available yet.

See Also:

• RequestLogProperty.SESSION

sessionProtocol

SessionProtocol sessionProtocol()

Returns the SessionProtocol of the Request.

Throws:

RequestLogAvailabilityException - if the property is not available yet.

See Also:

• RequestLogProperty.SESSION

connectionTimings

@Nullable
@Nullable ClientConnectionTimings connectionTimings()

Returns the ClientConnectionTimings of the Request.

Returns:

the ClientConnectionTimings if the Request involved a new connection attempt, or null otherwise.

Throws:

RequestLogAvailabilityException - if the property is not available yet.

See Also:

• RequestLogProperty.SESSION

serializationFormat

SerializationFormat serializationFormat()

Returns the SerializationFormat of the Request.

scheme

Scheme scheme()

Returns the Scheme of the Request.

Throws:

RequestLogAvailabilityException - if the property is not available yet.

See Also:

• RequestLogProperty.SCHEME

serviceName

@Nullable
@Nullable String serviceName()

Returns the human-readable name of the service that served the Request, such as:

• gRPC - a service name (e.g, com.foo.GrpcService)
• Thrift - a service type (e.g, com.foo.ThriftService$AsyncIface or com.foo.ThriftService$Iface)
• HttpService and annotated service - an innermost class name

This property is often used as a meter tag or distributed trace's span name.

name

String name()

Returns the human-readable simple name of the Request, such as:

• gRPC - A capitalized method name defined in io.grpc.MethodDescriptor (e.g, GetItems)
• Thrift and annotated service - a method name (e.g, getItems)
• HttpService - an HTTP method name

This property is often used as a meter tag or distributed trace's span name.

fullName

String fullName()

Returns the human-readable full name, which is the concatenation of serviceName() and name() using '/', of the Request. This property is often used as a meter tag or distributed trace's span name.

authenticatedUser

@Nullable
@Nullable String authenticatedUser()

Returns the authenticated user which is used to print %u format of an access log.

See Also:

• Custom Log Formats

requestHeaders

RequestHeaders requestHeaders()

Returns the RequestHeaders. If the Request was not received or sent at all, it will return a dummy RequestHeaders whose :authority and :path are set to "?", :scheme is set to "http" or "https", and :method is set to "UNKNOWN".

Throws:

RequestLogAvailabilityException - if the property is not available yet.

See Also:

• RequestLogProperty.REQUEST_HEADERS

requestContent

@Nullable
@Nullable Object requestContent()

Returns the high-level content object of the Request, which is specific to the SerializationFormat.

Throws:

RequestLogAvailabilityException - if the property is not available yet.

See Also:

• RequestLogProperty.REQUEST_CONTENT

rawRequestContent

@Nullable
@Nullable Object rawRequestContent()

Returns the low-level content object of the Request, which is specific to the SerializationFormat.

Returns:

ThriftCall for Thrift, or null for others

Throws:

RequestLogAvailabilityException - if the property is not available yet.

See Also:

• RequestLogProperty.REQUEST_CONTENT

requestContentPreview

@Nullable
@Nullable String requestContentPreview()

Returns the preview of request content of the Request. Note that a Service or a Client must be decorated with ContentPreviewingService or ContentPreviewingClient decorators respectively to enable the content preview.

Returns:

the preview, or null if the preview is disabled.

Throws:

RequestLogAvailabilityException - if the property is not available yet.

See Also:

• RequestLogProperty.REQUEST_CONTENT_PREVIEW

requestTrailers

HttpHeaders requestTrailers()

Returns the HTTP trailers of the Request.

Throws:

RequestLogAvailabilityException - if the property is not available yet.

See Also:

• RequestLogProperty.REQUEST_TRAILERS

toStringRequestOnly

@Deprecated
default String toStringRequestOnly()

Deprecated.

Use LogFormatter.formatRequest(RequestOnlyLog) instead.

Returns the string representation of the Request, with no sanitization of headers or content. This method is a shortcut for:

 toStringRequestOnly((ctx, headers) -> headers,
                     (ctx, content) -> content,
                     (ctx, trailers) -> trailers);
 

toStringRequestOnly

@Deprecated
default String toStringRequestOnly(BiFunction<? super RequestContext,? super HttpHeaders,? extends @Nullable Object> headersSanitizer,
 BiFunction<? super RequestContext,Object,? extends @Nullable Object> contentSanitizer)

Deprecated.

Use LogFormatter.formatRequest(RequestOnlyLog) instead.

Returns the string representation of the Request. This method is a shortcut for:

 toStringRequestOnly(headersSanitizer, contentSanitizer, headersSanitizer);
 

Parameters:

headersSanitizer - a BiFunction for sanitizing HTTP headers for logging. The result of the BiFunction is what is actually logged as headers.

contentSanitizer - a BiFunction for sanitizing request content for logging. The result of the BiFunction is what is actually logged as content.

toStringRequestOnly

@Deprecated
default String toStringRequestOnly(BiFunction<? super RequestContext,? super RequestHeaders,? extends @Nullable Object> headersSanitizer,
 BiFunction<? super RequestContext,Object,? extends @Nullable Object> contentSanitizer,
 BiFunction<? super RequestContext,? super HttpHeaders,? extends @Nullable Object> trailersSanitizer)

Deprecated.

Use LogFormatter.formatRequest(RequestOnlyLog) instead.

Returns the string representation of the Request.

Parameters:

headersSanitizer - a BiFunction for sanitizing HTTP headers for logging. The result of the BiFunction is what is actually logged as headers.

contentSanitizer - a Function for sanitizing request content for logging. The result of the BiFunction is what is actually logged as content.

trailersSanitizer - a BiFunction for sanitizing HTTP trailers for logging. The result of the BiFunction is what is actually logged as trailers.