com.dynatrace.oneagent.sdk.api.Tracer Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of oneagent-sdk Show documentation

Dynatrace OneAgent SDK for Java allows Dynatrace customers to instrument java applications, not supported out-of-the-box by Dynatrace OneAgent for Java.

There is a newer version: 1.9.0

Show newest version

/*
 * Copyright 2018 Dynatrace LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.dynatrace.oneagent.sdk.api;

/**
 * Common interface for timing-related methods. Not to be directly used by SDK
 * user.
 */
public interface Tracer {

	/**
	 * starts timing of a node. Every node that has been started, must be ended with
	 * {@link #end()} method. Consider using the following pattern:
	 *
	 * 	 * {@code
	 *   tracer.start();
	 *   try {
	 *     // do your work
	 *   } catch (Exception e) {
	 *     tracer.error(e);
	 *   } finally {
	 *     tracer.end();
	 *   }
	 * }
	 * 
	 *
	 * {@link #start()}, {@link #end()}, {@link #error(String)},
	 * {@link #error(Throwable)} are not thread-safe. They must be called from the
	 * same thread where {@link #start()} has been invoked.
	 *
	 * @since 1.0
	 */
	void start();

	/**
	 * Ends timing of a node. Typically this method is called via finally block.
	 * 

	 * {@link #start()}, {@link #end()}, {@link #error(String)},
	 * {@link #error(Throwable)} are not thread-safe. They must be called from the
	 * same thread where {@link #start()} has been invoked.
	 *
	 * @since 1.0
	 */
	void end();

	/**
	 * Marks the node as 'exited by exception'. An additional error message can be
	 * provided as String. 

	 * {@link #start()}, {@link #end()}, {@link #error(String)},
	 * {@link #error(Throwable)} are not thread-safe. They must be called from the
	 * same thread where {@link #start()} has been invoked.
	 *
	 * @param message
	 *            error message with details about occurred error (eg. return code).
	 *            must not be null.
	 * @since 1.0
	 */
	void error(String message);

	/**
	 * Marks the node as 'exited by exception'.Additional information can be
	 * provided as Throwable. 

	 * {@link #start()}, {@link #end()}, {@link #error(String)},
	 * {@link #error(Throwable)} are not thread-safe. They must be called from the
	 * same thread where {@link #start()} has been invoked.
	 *
	 * @param throwable
	 *            exception, that occurred. must not null.
	 * @since 1.0
	 */
	void error(Throwable throwable);
}