Package com.linecorp.armeria.common.logging

Interface RequestLogBuilder

All Superinterfaces:

RequestLogAccess

public interface RequestLogBuilder
extends RequestLogAccess

Updates a RequestLog with newly available information.

Method Summary

Modifier and Type	Method	Description
void	addChild(RequestLogAccess child)	Adds the specified RequestLogAccess so that the logs are propagated from the child.
void	authenticatedUser(String authenticatedUser)	Sets the remote user of the request if it's authenticated.
void	defer(RequestLogProperty property)	Allows setting the specified RequestLogProperty even after endResponse() or endResponse(Throwable) called.
void	defer(RequestLogProperty... properties)	Allows setting the specified RequestLogPropertys even after endResponse() or endResponse(Throwable) called.
void	defer(Iterable<RequestLogProperty> properties)	Allows setting the specified RequestLogPropertys even after endResponse() or endResponse(Throwable) called.
void	endRequest()	Finishes the collection of the Request information.
void	endRequest(long requestEndTimeNanos)	Finishes the collection of the Request information.
void	endRequest(Throwable requestCause)	Finishes the collection of the Request information.
void	endRequest(Throwable requestCause, long requestEndTimeNanos)	Finishes the collection of the Request information.
void	endResponse()	Finishes the collection of the Response information.
void	endResponse(long responseEndTimeNanos)	Finishes the collection of the Response information.
void	endResponse(Throwable responseCause)	Finishes the collection of the Response information.
void	endResponse(Throwable responseCause, long responseEndTimeNanos)	Finishes the collection of the Response information.
void	endResponseWithLastChild()	Fills the response-side logs from the last added child.
void	increaseRequestLength(long deltaBytes)	Increases the RequestOnlyLog.requestLength() by deltaBytes.
void	increaseRequestLength(HttpData data)	Increases the RequestOnlyLog.requestLength() by data.length() and passes data to the previewer.
void	increaseResponseLength(long deltaBytes)	Increases the RequestLog.responseLength() by deltaBytes.
void	increaseResponseLength(HttpData data)	Increases the RequestLog.responseLength() by data.length() and passes data to the previewer.
boolean	isDeferred(RequestLogProperty property)	Returns true if the specified RequestLogProperty has been deferred with defer(RequestLogProperty).
boolean	isDeferred(RequestLogProperty... properties)	Returns true if all of the specified RequestLogPropertys have been deferred with defer(RequestLogProperty).
boolean	isDeferred(Iterable<RequestLogProperty> properties)	Returns true if all of the specified RequestLogPropertys have been deferred with defer(RequestLogProperty).
void	name(String name)	Sets the human-readable name of the Request, such as RPC method name, annotated service method name or HTTP method name.
void	name(String serviceName, String name)	Sets the human-readable service name and method name of the Request such as: A service and method name for gRPC and Thrift An innermost class and method name for annotated service A path pattern and HTTP method name for HttpService This property is often used as a meter tag or distributed trace's span name.
void	requestContent(@Nullable Object requestContent, @Nullable Object rawRequestContent)	Sets the RequestOnlyLog.requestContent() and the RequestOnlyLog.rawRequestContent().
void	requestContentPreview(@Nullable String requestContentPreview)	Sets the RequestOnlyLog.requestContentPreview().
void	requestFirstBytesTransferred()	Sets RequestOnlyLog.requestFirstBytesTransferredTimeNanos().
void	requestFirstBytesTransferred(long requestFirstBytesTransferredNanos)	Sets RequestOnlyLog.requestFirstBytesTransferredTimeNanos() with the specified timestamp.
void	requestHeaders(RequestHeaders requestHeaders)	Sets the RequestOnlyLog.requestHeaders().
void	requestLength(long requestLength)	Sets the RequestOnlyLog.requestLength().
void	requestTrailers(HttpHeaders requestTrailers)	Sets the RequestOnlyLog.requestTrailers().
void	responseCause(Throwable cause)	Sets the RequestLog.responseCause() without completing the response log.
void	responseContent(@Nullable Object responseContent, @Nullable Object rawResponseContent)	Sets the RequestLog.responseContent() and the RequestLog.rawResponseContent().
void	responseContentPreview(@Nullable String responseContentPreview)	Sets the RequestLog.responseContentPreview().
void	responseFirstBytesTransferred()	Sets RequestLog.responseFirstBytesTransferredTimeNanos().
void	responseFirstBytesTransferred(long responseFirstBytesTransferredNanos)	Sets RequestLog.responseFirstBytesTransferredTimeNanos() with the specified timestamp.
void	responseHeaders(ResponseHeaders responseHeaders)	Sets the RequestLog.responseHeaders().
void	responseLength(long responseLength)	Sets the RequestLog.responseLength().
void	responseTrailers(HttpHeaders responseTrailers)	Sets the RequestLog.responseTrailers().
void	serializationFormat(SerializationFormat serializationFormat)	Sets the SerializationFormat.
void	session(@Nullable Channel channel, SessionProtocol sessionProtocol, @Nullable ClientConnectionTimings connectionTimings)	Sets the properties related with socket connection.
void	session(@Nullable Channel channel, SessionProtocol sessionProtocol, @Nullable SSLSession sslSession, @Nullable ClientConnectionTimings connectionTimings)	Sets the properties related with socket connection.
default void	startRequest()	Starts the collection of the Request information.
void	startRequest(long requestStartTimeNanos, long requestStartTimeMicros)	Starts the collection of the Request information.
void	startResponse()	Starts the collection of Response information.
void	startResponse(long responseStartTimeNanos, long responseStartTimeMicros)	Starts the collection of Response information.

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

startRequest

default void startRequest()

Starts the collection of the Request information. This method sets the following properties:

• RequestOnlyLog.requestStartTimeMillis()
• RequestOnlyLog.requestStartTimeMicros()
• RequestOnlyLog.requestStartTimeNanos()

startRequest

void startRequest(long requestStartTimeNanos,
 long requestStartTimeMicros)

Starts the collection of the Request information. This method sets the following properties:

• RequestOnlyLog.requestStartTimeMillis()
• RequestOnlyLog.requestStartTimeMicros()
• RequestOnlyLog.requestStartTimeNanos()

Parameters:

requestStartTimeNanos - System.nanoTime() value when the request started.

requestStartTimeMicros - the number of microseconds since the epoch, e.g. System.currentTimeMillis() * 1000.

session

void session(@Nullable
 @Nullable Channel channel,
 SessionProtocol sessionProtocol,
 @Nullable
 @Nullable ClientConnectionTimings connectionTimings)

Sets the properties related with socket connection. This method sets the following properties:

• RequestOnlyLog.channel()
• RequestOnlyLog.sessionProtocol()
• RequestOnlyLog.sslSession()

Parameters:

channel - the Channel which handled the Request.

sessionProtocol - the SessionProtocol of the connection.

session

void session(@Nullable
 @Nullable Channel channel,
 SessionProtocol sessionProtocol,
 @Nullable
 @Nullable SSLSession sslSession,
 @Nullable
 @Nullable ClientConnectionTimings connectionTimings)

Sets the properties related with socket connection. This method sets the following properties:

• RequestOnlyLog.channel()
• RequestOnlyLog.sessionProtocol()
• RequestOnlyLog.sslSession()

Parameters:

channel - the Channel which handled the Request.

sessionProtocol - the SessionProtocol of the connection.

sslSession - the SSLSession of the connection, or null.

serializationFormat

void serializationFormat(SerializationFormat serializationFormat)

Sets the SerializationFormat.

name

void name(String serviceName,
 String name)

Sets the human-readable service name and method name of the Request such as:

• A service and method name for gRPC and Thrift
• An innermost class and method name for annotated service
• A path pattern and HTTP method name for HttpService

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

name

void name(String name)

Sets the human-readable name of the Request, such as RPC method name, annotated service method name or HTTP method name. This property is often used as a meter tag or distributed trace's span name.

authenticatedUser

void authenticatedUser(String authenticatedUser)

Sets the remote user of the request if it's authenticated. The value will be printed out if the access log has %u format.

See Also:

• Custom Log Formats

increaseRequestLength

void increaseRequestLength(long deltaBytes)

Increases the RequestOnlyLog.requestLength() by deltaBytes.

increaseRequestLength

void increaseRequestLength(HttpData data)

Increases the RequestOnlyLog.requestLength() by data.length() and passes data to the previewer.

requestLength

void requestLength(long requestLength)

Sets the RequestOnlyLog.requestLength().

requestFirstBytesTransferred

void requestFirstBytesTransferred()

Sets RequestOnlyLog.requestFirstBytesTransferredTimeNanos().

requestFirstBytesTransferred

void requestFirstBytesTransferred(long requestFirstBytesTransferredNanos)

Sets RequestOnlyLog.requestFirstBytesTransferredTimeNanos() with the specified timestamp.

requestHeaders

void requestHeaders(RequestHeaders requestHeaders)

Sets the RequestOnlyLog.requestHeaders().

requestContent

void requestContent(@Nullable
 @Nullable Object requestContent,
 @Nullable
 @Nullable Object rawRequestContent)

Sets the RequestOnlyLog.requestContent() and the RequestOnlyLog.rawRequestContent(). If the specified requestContent is an RpcRequest and the RequestContext.rpcRequest() is null, this method will call RequestContext.updateRpcRequest(RpcRequest).

requestContentPreview

void requestContentPreview(@Nullable
 @Nullable String requestContentPreview)

Sets the RequestOnlyLog.requestContentPreview().

requestTrailers

void requestTrailers(HttpHeaders requestTrailers)

Sets the RequestOnlyLog.requestTrailers().

endRequest

void endRequest()

Finishes the collection of the Request information. This method sets the following properties:

• RequestOnlyLog.requestEndTimeNanos()
• RequestOnlyLog.requestDurationNanos()
• RequestOnlyLog.requestCause()

endRequest

void endRequest(Throwable requestCause)

Finishes the collection of the Request information. This method sets the following properties:

• RequestOnlyLog.requestEndTimeNanos()
• RequestOnlyLog.requestDurationNanos()
• RequestOnlyLog.requestCause()

Parameters:

requestCause - the cause of the failure.

endRequest

void endRequest(long requestEndTimeNanos)

Finishes the collection of the Request information. This method sets the following properties:

• RequestOnlyLog.requestEndTimeNanos()
• RequestOnlyLog.requestDurationNanos()
• RequestOnlyLog.requestCause()

Parameters:

requestEndTimeNanos - System.nanoTime() value when the request ended.

endRequest

void endRequest(Throwable requestCause,
 long requestEndTimeNanos)

Finishes the collection of the Request information. This method sets the following properties:

• RequestOnlyLog.requestEndTimeNanos()
• RequestOnlyLog.requestDurationNanos()
• RequestOnlyLog.requestCause()

Parameters:

requestCause - the cause of the failure.

requestEndTimeNanos - System.nanoTime() value when the request ended.

startResponse

void startResponse()

Starts the collection of Response information. This method sets the following properties:

• RequestLog.responseStartTimeMillis()
• RequestLog.responseStartTimeMicros()
• RequestLog.responseStartTimeNanos()

startResponse

void startResponse(long responseStartTimeNanos,
 long responseStartTimeMicros)

Starts the collection of Response information. This method sets the following properties:

• RequestLog.responseStartTimeMillis()
• RequestLog.responseStartTimeMicros()
• RequestLog.responseStartTimeNanos()

Parameters:

responseStartTimeNanos - System.nanoTime() value when the response started.

responseStartTimeMicros - the number of microseconds since the epoch, e.g. System.currentTimeMillis() * 1000.

increaseResponseLength

void increaseResponseLength(long deltaBytes)

Increases the RequestLog.responseLength() by deltaBytes.

increaseResponseLength

void increaseResponseLength(HttpData data)

Increases the RequestLog.responseLength() by data.length() and passes data to the previewer.

responseLength

void responseLength(long responseLength)

Sets the RequestLog.responseLength().

responseFirstBytesTransferred

void responseFirstBytesTransferred()

Sets RequestLog.responseFirstBytesTransferredTimeNanos().

responseFirstBytesTransferred

void responseFirstBytesTransferred(long responseFirstBytesTransferredNanos)

Sets RequestLog.responseFirstBytesTransferredTimeNanos() with the specified timestamp.

responseHeaders

void responseHeaders(ResponseHeaders responseHeaders)

Sets the RequestLog.responseHeaders().

responseContent

void responseContent(@Nullable
 @Nullable Object responseContent,
 @Nullable
 @Nullable Object rawResponseContent)

Sets the RequestLog.responseContent() and the RequestLog.rawResponseContent().

responseContentPreview

void responseContentPreview(@Nullable
 @Nullable String responseContentPreview)

Sets the RequestLog.responseContentPreview().

responseTrailers

void responseTrailers(HttpHeaders responseTrailers)

Sets the RequestLog.responseTrailers().

responseCause

void responseCause(Throwable cause)

Sets the RequestLog.responseCause() without completing the response log. This method may be useful if you want to send additional data even after an exception is raised. If you want to end the response log right away when an exception is raised, please use endResponse(Throwable).

endResponse

void endResponse()

Finishes the collection of the Response information. If a Throwable cause has been set with responseContent(Object, Object), it will be treated as the responseCause for this log. This method sets the following properties:

• RequestLog.responseEndTimeNanos()
• RequestLog.responseDurationNanos()
• RequestLog.responseCause()

endResponse

void endResponse(Throwable responseCause)

Finishes the collection of the Response information. This method sets the following properties:

• RequestLog.responseEndTimeNanos()
• RequestLog.responseDurationNanos()
• RequestLog.responseCause()

Parameters:

responseCause - the cause of the failure.

endResponse

void endResponse(long responseEndTimeNanos)

Finishes the collection of the Response information. If a Throwable cause has been set with responseContent(Object, Object), it will be treated as the responseCause for this log. This method sets the following properties:

• RequestLog.responseEndTimeNanos()
• RequestLog.responseDurationNanos()
• RequestLog.responseCause()

Parameters:

responseEndTimeNanos - System.nanoTime() value when the response ended.

endResponse

void endResponse(Throwable responseCause,
 long responseEndTimeNanos)

Finishes the collection of the Response information. This method sets the following properties:

• RequestLog.responseEndTimeNanos()
• RequestLog.responseDurationNanos()
• RequestLog.responseCause()

Parameters:

responseCause - the cause of the failure.

responseEndTimeNanos - System.nanoTime() value when the response ended.

isDeferred

boolean isDeferred(RequestLogProperty property)

Returns true if the specified RequestLogProperty has been deferred with defer(RequestLogProperty).

isDeferred

boolean isDeferred(RequestLogProperty... properties)

Returns true if all of the specified RequestLogPropertys have been deferred with defer(RequestLogProperty).

isDeferred

boolean isDeferred(Iterable<RequestLogProperty> properties)

Returns true if all of the specified RequestLogPropertys have been deferred with defer(RequestLogProperty).

defer

void defer(RequestLogProperty property)

Allows setting the specified RequestLogProperty even after endResponse() or endResponse(Throwable) called. Once this method is called, the caller must ensure to call the setter of the specified RequestLogProperty, because otherwise the RequestLog will never be completed.

Note, however, the following RequestLogPropertys will be set automatically when the RequestLog has ended with an exception:

• RequestLogProperty.REQUEST_CONTENT
• RequestLogProperty.REQUEST_CONTENT_PREVIEW
• RequestLogProperty.RESPONSE_CONTENT
• RequestLogProperty.RESPONSE_CONTENT_PREVIEW

defer

void defer(RequestLogProperty... properties)

Allows setting the specified RequestLogPropertys even after endResponse() or endResponse(Throwable) called. Once this method is called, the caller must ensure to call the setters of the specified RequestLogPropertys, because otherwise the RequestLog will never be completed.

Note, however, the following RequestLogPropertys will be set automatically when the RequestLog has ended with an exception:

• RequestLogProperty.REQUEST_CONTENT
• RequestLogProperty.REQUEST_CONTENT_PREVIEW
• RequestLogProperty.RESPONSE_CONTENT
• RequestLogProperty.RESPONSE_CONTENT_PREVIEW

defer

void defer(Iterable<RequestLogProperty> properties)

Allows setting the specified RequestLogPropertys even after endResponse() or endResponse(Throwable) called. Once this method is called, the caller must ensure to call the setters of the specified RequestLogPropertys, because otherwise the RequestLog will never be completed.

Note, however, the following RequestLogPropertys will be set automatically when the RequestLog has ended with an exception:

• RequestLogProperty.REQUEST_CONTENT
• RequestLogProperty.REQUEST_CONTENT_PREVIEW
• RequestLogProperty.RESPONSE_CONTENT
• RequestLogProperty.RESPONSE_CONTENT_PREVIEW

addChild

void addChild(RequestLogAccess child)

Adds the specified RequestLogAccess so that the logs are propagated from the child. Note that only the request-side logs of the first added child will be propagated. To fill the response-side logs you need to call endResponseWithLastChild().

endResponseWithLastChild

void endResponseWithLastChild()

Fills the response-side logs from the last added child. Note that already collected properties in the child log will be propagated immediately.