A TeamCity plugin that sends build trace data to an OpenTelemetry collector endpoint.
This plugin helps you visualize how you can better optimize your TeamCity builds and their dependency trees, by exporting TeamCity build pipeline data automatically to existing OpenTelemetry collector such as Honeycomb, Zipkin or Jaeger.
From the OpenTelemetry docs:
You can use OpenTelemetry to instrument, generate, collect, and export telemetry data (metrics, logs, and traces) for analysis in order to understand your software's performance and behavior. Create and collect telemetry data from your services and software, then forward them to a variety of analysis tools. For more information about OpenTelemetry go to https://opentelemetry.io/.
- Build the plugin using the "Building" instructions below.
- In your TeamCity instance go to the configuration settings for the project which you want to start sending data for (the root project is a good candidate for sending everything!), and choose
OpenTelemetry
in the left menu - Tick Enable, and enter the required settings
- If you are using honeycomb.io, use the following settings:
- Service:
Honeycomb.io
- Api Key: The honeycomb.io api key
- Team: Your team name from honeycomb (as shown in the browser url)
- Dataset: The dataset you want to send data to
- Service:
- If you are using Zipkin.io:
- Service:
Zipkin
- Endpoint: The url of your zipkin instance (eg
http://localhost:9411/
)
- Service:
- If you are using another service, use the following settings:
- Service:
Custom
- Endpoint: The url of the service
- Headers: The service specific headers required
- Service:
- If you are using honeycomb.io, use the following settings:
- Note that settings are inherited and can be overridden by child project settings
- Install the .zip using your TeamCity instance UI via Administration -> Plugins -> Upload. Restart if required.
To view logs from the plugin, add the following sections to the conf/teamcity-server-log4j.xml
file in your teamcity installation:
Under Appenders
:
<DelegateAppender>
<RollingFile name="OTEL.LOG" fileName="${sys:teamcity_logs}/teamcity-otel-plugin.log"
filePattern="${sys:teamcity_logs}/teamcity-otel-plugin.log.%i"
append="true" createOnDemand="true">
<PatternLayout pattern="[%d] %6p - %30.30c - %m%n" charset="UTF-8"/>
<SizeBasedTriggeringPolicy size="10 MB"/>
<DefaultRolloverStrategy max="3" fileIndex="min"/>
</RollingFile>
</DelegateAppender>
Under Loggers
:
<Logger name="com.octopus.teamcity.opentelemetry" level="DEBUG">
<AppenderRef ref="OTEL.LOG" />
</Logger>
For detailed instructions check the TeamCity docker hub docs.
- Ensure you have docker running
- Run
docker pull jetbrains/teamcity-server
- Run
docker run -it --name teamcity-server-instance \
-v <path-to-data-directory>:/data/teamcity_server/datadir \
-v <path-to-logs-directory>:/opt/teamcity/logs \
-p <port-on-host>:8111 \
jetbrains/teamcity-server
- Run
docker pull jetbrains/teamcity-agent
- Run
docker run -it -e SERVER_URL="<url to TeamCity server>" \
-v <path to agent config folder>:/data/teamcity_agent/conf \
jetbrains/teamcity-agent
You must have a TeamCity instance running. To run a TeamCity instance locally:
- Download the TeamCity distro for your OS from https://www.jetbrains.com/teamcity/download/#section=on-premises.
- Unzip the distro and place in a directory of your choosing.
- To run the default server, open terminal then cd in your TeamCity directory then run
./bin/teamcity-server.sh run
. An alias these commands for repeated future can be made. - In a separate terminal, to run the default agent, cd in your TeamCity directory then run
./buildAgent/bin/agent.sh run
. - Open localhost:8111 in a browser.
- On your first run create an admin login (this setup only needs to take place once due to the configuration mount). Once the server starts up, navigate to Agents->Unauthorized and authorise the agent that was started in a container alongside the server.
- (Optional) If attaching a remote debugger run in your TeamCity directory
export TEAMCITY_SERVER_OPTS=-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8111 && $SCRIPT_PATH/bin/teamcity-server.sh run
for the server andexport TEAMCITY_SERVER_OPTS=-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8111 && $SCRIPT_PATH/buildAgent/bin/agent.sh run
for the default agent. - Configure the settings as per
Installing the plugin to TeamCity
above. - To stop the TeamCity server and agent from running, in a separate terminal cd to your TeamCity directory and run
./bin/runAll.sh stop
To build the plugin from code:
- Ensure your
$JAVA_HOME
points to a java11 JDK installation - Install TeamCity
- Inside the root project folder run
./gradlew build
. The gradlew script will download Gradle for you if it is not already installed. - The plugin is available at
<project_root>/build/distributions/Octopus.TeamCity.OpenTelemetry.<version>.zip
. - Copy to
.zip
to your TeamCitydata_dir/plugins
directory and restart TeamCity server OR install the.zip
using your TeamCity instance UI.
JUnit tests have been added to package test folders.
To test the plugin from code:
- Ensure your
$JAVA_HOME
points to a java11 JDK installation - Inside the root project folder run
./gradlew test
. The gradlew script will download Gradle for you if it is not already installed.
To clean the project root directory of builds:
- Inside the root project folder run
./gradlew clean
. The gradlew script will download Gradle for you if it is not already installed.