Disclaimer: This article is based on the author’s opinion and should not be taken as official documentation on how to enter info for a support case with Alfresco Enterprise Support.
More often than not, we support guys have to ask for things like log files, settings, component types and versions and even compressed directories (and a whole lot of other things depending on the situation!). I work at Alfresco and this article is aimed at mostly our customers but it also will help you work with support professionals who are trying to help you solve problems for many different types of software.
Let’s be honest, a lot of these requests can be very tedious. They were for me when I worked as a SysAdmin or developer in the past. Perhaps you have another case open with another support member and you’ve already submitted the same logs there. Or it’s possible that you finished getting another problem solved and submitted many artifacts there very recently.
I can certainly empathize. As a sysadmin in the past, I worked very often with an enterprise-class database server (I won’t name it but it starts with a D and end with a 2). Since we had no DBA there, I had to open a number of tickets with support to solve many issues I was not familiar with. The support for this particular company seemed at times very unsympathetic and cold to me. They would continuously ask for settings and log files. It did however make sense later that they had no idea what was going on in my environment at that particular time especially if they gave me some settings to try that did not work after testing them.
There are other times when you might have submitted current artifacts on another active case. You can let the support person who is working your case know that. You can tell them where it is (attached to another case, on an ftp server, etc) and that you believe it to be the most current. Any reasonable support person would be more than happy to help gather them and attach the files to the case at hand. Just be aware that it may take the agent a little bit of extra time to find it in some instances but if you are ok with that, we are too.
There are a number of different artifacts that we ask for to help us determine the environment and what could be going wrong. What do we normally ask for and why?
- alfresco.log – gives us an idea from an Alfresco perspective what’s going on from startup and we can see what’s going on when you replicate the steps that are causing the issue.
- share.log – since around 4.1.1 this was introduced so that we get very specific information about Share in its own log file.
- solr.log – similar to share.log except it gives us specific info on Solr (the more recent index subsystem added to Alfresco)
- catalina.out, stdout.log, stderr.log, etc. – These are Tomcat log files. They can help us in some instances determine the cause of Alfresco not starting, memory errors, http issues, etc. The catalina.out will also include the same info as alfresco.log. In many cases, it’s best to have this as it will include the same info found in alfresco.log, share.log, solr.log. However in some advanced problems this file can be too big to effectively read. We do try to parse with ‘grep’ but we may request seperate logs in some situations to get more clarity.
The most efficient way to gather log files is to follow these steps:
- Stop Alfresco
- Clear all log files (delete if not needed, rotate and/or backup if they are needed)
- Add any debug statements relevant to the issue given to you by your Support agent to log4j.properties (tomcat/webapps/alfresco/WEB-INF/classes/).
- Start Alfresco
- Perform the steps that replicate and reveal the issue
- Compress log files together and attach back to the case.
- alfresco-global.properties – After Alfresco 3.1, alfresco-global.properties was introduced as a unified settings file. This can give us very quick visibility into your settings that you’ve added.
- JMX Dump – A JMX dump will give us a very holistic and effective group of settings that Alfresco is using at a given time. Think of it in a way as a snapshot of your system. A big reason we ask for it is while you may have certain setting values in alfresco-global.properties they may not be used at that time because it’s possible a user has changed settings using the JConsole. The settings from JConsole that are added will override any property settings in the files until you go back in via JConsole and change them back. While it doesn’t tell us *everything* , it is the most effective way of us knowing exactly what your Alfresco settings are at a given point in time.
- Compressed tomcat/shared/classes directory – For those wishing to customize their Alfresco installation, this is the start of where those files should be. Also, in situations that call for multiple means of the same type of authentication and user/group synchronization (example: multiple Active Directory servers/domains) the user will have to create additional configuration settings. For example, in this situatio these will be found in tomcat/shared/classes/alfresco/extension/Subsystems/authentication. It’s very good to have this when troubleshooting customizations.
As mentioned about log files, it’s very helpful to have all of these settings files compressed too and added with logs.
- screenshots – If you’re having a UI issue or you encounter an error that only shows up in the UI (and not in the logs), a screenshot can help us very quickly determine what’s going on. These should only be used when copying text is not an option.
- thread dumps, heap dumps – Dumps are great for helping to solve performance or memory issues.
The settings and log files are valuable to us. We do our best to keep from requesting files that are not necessary but usually we will need to see them all again after we suggest some corrective action or when we know a change was made to the system. It’s easy to forget or misspell something. Believe it or not, most settings errors are because of this. The next group of things we may ask for is types and versions of Alfresco components. More than likely we only have to ask for these once per case:
- OS type and version, 64bit or 32bit?
- Alfresco version
- JDK version
- Database type and version
- Application server type and version
- OS type and version
- Browser type and version
- Office version
3rd party (optional and when needed)
- OpenOffice (or LibreOffice) version
- ImageMagick version
- Swftools version
- Kofax, Transformation server, etc. version
We need to know these things because like almost all Enterprise software out there, Alfresco maintains a list of supported software that is used by our product. In a lot of cases, the user uses the Alfresco package installer. This installer ensures you are using the supported versions of everything needed. In this case, if you’re asked for Alfresco server-side versions, just let your support technician know if you’ve installed Alfresco with our standard installer.
For client-side issues (SharePoint protocol, custom UI, etc.), we will most likely need to know things like client OS type and versions, browser and MS Office version.
We need to know these things because each Alfresco version is only certified with a particular mix of components. If we have to go to an advanced engineer or developer, they will insist on a supported software stack. Adding too many different platforms to our supported ones adds complexity to possible issues that arise and to our development/QA cycle which can be very expensive and more difficult to support and maintain for you, the customer.
How do I compress files to send them back to you?
Ideally it’s best to use only standard tools. I try to make sure I have compression tools so I can handle things like 7-zip, RAR and zx files. However, some of these don’t work on every laptop that a support person has. While I may have them on mine, we occasionally have to pass cases on to other support technicians and they may not have these tools. It’s best to use these:
- tar – Linux/Mac OS X
- gzip/bzip2 – Linux/Mac OS X
- zip – Windows
If you’re unable to use these compression tools on your system or it’s not practical, no worries, just send them in the best way you can.
Hopefully all of this is helpful and makes sense when you open a case with us and a support tech is asking for these files. It really does help us solve your issue quicker when you help us help you